Merge pull request #7855 from XRPLF/mvadari/wasmi-tests-update-july

chore: Update `ripple/se/wasmi-tests` to the latest

.clang-tidy

@@ -56,32 +56,17 @@ Checks: "-*,
 
   readability-*,
   -readability-avoid-const-params-in-decls,
-  -readability-avoid-unconditional-preprocessor-if,
   -readability-container-data-pointer,
-  -readability-delete-null-pointer,
   -readability-function-cognitive-complexity,
-  -readability-function-size,
   -readability-identifier-length,
   -readability-inconsistent-declaration-parameter-name,
   -readability-isolate-declaration,
   -readability-magic-numbers,
-  -readability-misplaced-array-index,
   -readability-named-parameter,
-  -readability-operators-representation,
   -readability-qualified-auto,
   -readability-redundant-access-specifiers,
-  -readability-redundant-control-flow,
-  -readability-redundant-function-ptr-dereference,
-  -readability-redundant-preprocessor,
-  -readability-redundant-smartptr-get,
-  -readability-redundant-string-cstr,
-  -readability-simplify-subscript-expr,
   -readability-static-accessed-through-instance,
-  -readability-string-compare,
-  -readability-uniqueptr-delete-release,
-  -readability-uppercase-literal-suffix,
-  -readability-use-anyofallof,
-  -readability-use-concise-preprocessor-directives
+  -readability-uppercase-literal-suffix
   "
 # ---
 # bugprone-narrowing-conversions,                      # This will break a lot of code but we should enable it in the future because it can eliminate a lot of bugs

.cspell.config.yaml

@@ -7,6 +7,8 @@ ignorePaths:
   - cmake/**
   - LICENSE.md
   - .clang-tidy
+  - src/test/app/wasm_fixtures/**/*.wat
+  - src/test/app/wasm_fixtures/*.c
 language: en
 allowCompoundWords: true # TODO (#6334)
 ignoreRandomStrings: true
@@ -65,6 +67,8 @@ words:
   - Btrfs
   - Buildx
   - canonicality
+  - cdylib
+  - canonicalised
   - changespq
   - checkme
   - choco
@@ -72,6 +76,7 @@ words:
   - citardauq
   - clawback
   - clawbacks
+  - clippy
   - cmaketoolchain
   - coeffs
   - coldwallet
@@ -214,6 +219,7 @@ words:
   - Nyffenegger
   - onlatest
   - ostr
+  - oxalica
   - pargs
   - partitioner
   - paychan
@@ -259,6 +265,9 @@ words:
   - rocksdb
   - Rohrs
   - roundings
+  - rustc
+  - rustfmt
+  - rustup
   - sahyadri
   - Satoshi
   - scons
@@ -287,6 +296,7 @@ words:
   - STATSDCOLLECTOR
   - stissue
   - stnum
+  - stnumber
   - stobj
   - stobject
   - stpath
@@ -302,6 +312,7 @@ words:
   - takerpays
   - ters
   - TMEndpointv2
+  - toolchain
   - tparam
   - trixie
   - tx
@@ -334,6 +345,7 @@ words:
   - unsquelch
   - unsquelched
   - unsquelching
+  - unsuffixed
   - unvalidated
   - unveto
   - unvetoed
@@ -351,6 +363,7 @@ words:
   - wthread
   - xbridge
   - xchain
+  - xfloat
   - ximinez
   - XMACRO
   - xrpkuwait

.gersemi/definitions.cmake

@@ -11,6 +11,9 @@ endfunction()
 function(create_symbolic_link target link)
 endfunction()
 
+function(xrpl_add_benchmark name)
+endfunction()
+
 macro(exclude_from_default target_)
 endmacro()
 

.github/pull_request_template.md

@@ -1,10 +1,10 @@
 <!--
-This PR template helps you to write a good pull request description.
+This PR template helps you write a good pull request description.
 Please feel free to include additional useful information even beyond what is requested below.
 
 If your branch is on a personal fork and has a name that allows it to
 run CI build/test jobs (e.g. "ci/foo"), remember to rename it BEFORE
-opening the PR.  This avoids unnecessary redundant test runs. Renaming
+opening the PR. This avoids redundant test runs. Renaming
 the branch after opening the PR will close the PR.
 https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch
 -->
@@ -15,7 +15,7 @@ https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-
 Please include a summary of the changes.
 This may be a direct input to the release notes.
 If too broad, please consider splitting into multiple PRs.
-If a relevant task or issue, please link it here.
+If there is a relevant task or issue, please link it here.
 -->
 
 ### Context of Change
@@ -65,5 +65,5 @@ This section may not be needed if your change includes thoroughly commented unit
 
 <!--
 ## Future Tasks
-For future tasks related to PR.
+For future tasks related to this PR.
 -->

.github/scripts/levelization/results/ordering.txt

@@ -1,3 +1,6 @@
+benchmarks.libxrpl > xrpl.basics
+benchmarks.libxrpl > xrpl.config
+benchmarks.libxrpl > xrpl.nodestore
 libxrpl.basics > xrpl.basics
 libxrpl.conditions > xrpl.basics
 libxrpl.conditions > xrpl.conditions
@@ -159,6 +162,7 @@ test.peerfinder > xrpl.protocol
 test.protocol > test.jtx
 test.protocol > test.unit_test
 test.protocol > xrpl.basics
+test.protocol > xrpld.core
 test.protocol > xrpl.json
 test.protocol > xrpl.protocol
 test.rpc > test.jtx

.github/scripts/strategy-matrix/generate.py

@@ -25,24 +25,16 @@ def get_cmake_args(build_type: str, extra_args: str) -> str:
     return " ".join(args)
 
 
-def runs_on_event(exclude_event_types: list[str], event: str | None) -> bool:
-    """Whether a config should run for the current event.
-
-    'exclude_event_types' is a list of GitHub event names (e.g.
-    ["pull_request"]) on which the config should NOT run; an empty list means
-    the config runs on every event. When no event is given (event is None), no
-    filtering is applied.
-    """
-    if event is None:
-        return True
-    return event not in exclude_event_types
-
-
 # ---------------------------------------------------------------------------
 # Input types — shapes of the JSON config files
 # ---------------------------------------------------------------------------
 
 
+# Every config must declare 'minimal'. Minimal configs form the reduced matrix
+# built for pull requests by default; the full matrix adds the rest. Packaging
+# configs declare it too, but packaging is gated in the workflow, not by it.
+
+
 @dataclasses.dataclass
 class LinuxConfig:
     """One entry in linux.json's 'configs' or 'package_configs' arrays."""
@@ -50,13 +42,11 @@ class LinuxConfig:
     compiler: list[str]
     build_type: list[str]
     arch: list[str]
+    minimal: bool
     sanitizers: list[str] = dataclasses.field(default_factory=list)
     suffix: str = ""
     extra_cmake_args: str = ""
     image: str = ""  # only used by package_configs entries
-    # List of GitHub event names (e.g. "pull_request") on which this config
-    # should NOT run. Empty means it runs on every event.
-    exclude_event_types: list[str] = dataclasses.field(default_factory=list)
 
 
 @dataclasses.dataclass
@@ -89,11 +79,9 @@ class PlatformConfig:
     """One entry in macos.json's or windows.json's 'configs' array."""
 
     build_type: list[str]
+    minimal: bool
     build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
     extra_cmake_args: str = ""
-    # List of GitHub event names (e.g. "pull_request") on which this config
-    # should NOT run. Empty means it runs on every event.
-    exclude_event_types: list[str] = dataclasses.field(default_factory=list)
 
     def __post_init__(self) -> None:
         if isinstance(self.build_type, str):
@@ -168,20 +156,18 @@ _ARCHS: dict[str, Architecture] = {
 }
 
 
-def expand_linux_matrix(
-    linux: LinuxFile, event: str | None = None
-) -> list[MatrixEntry]:
+def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
     """Expand a LinuxFile into a flat list of matrix entries.
 
     Each config entry is expanded over the cross-product of its
-    compiler, build_type, sanitizers, and architecture lists. Configs that
-    exclude the current event are skipped.
+    compiler, build_type, sanitizers, and architecture lists. When 'minimal' is
+    true, only configs flagged as minimal are included.
     """
     entries: list[MatrixEntry] = []
 
     for distro, configs in linux.configs.items():
         for cfg in configs:
-            if not runs_on_event(cfg.exclude_event_types, event):
+            if minimal and not cfg.minimal:
                 continue
             # An empty sanitizers list means "one entry with no sanitizer".
             effective_sanitizers = cfg.sanitizers or [""]
@@ -240,19 +226,17 @@ def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
     return entries
 
 
-def expand_platform_matrix(
-    pf: PlatformFile, event: str | None = None
-) -> list[MatrixEntry]:
+def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]:
     """Expand a PlatformFile (macOS or Windows) into matrix entries.
 
-    Configs that exclude the current event are skipped.
+    When 'minimal' is true, only configs flagged as minimal are included.
     """
     platform_name, arch = pf.platform.split("/")
     is_windows = platform_name == "windows"
 
     entries: list[MatrixEntry] = []
     for cfg in pf.configs:
-        if not runs_on_event(cfg.exclude_event_types, event):
+        if minimal and not cfg.minimal:
             continue
         for build_type in cfg.build_type:
             entries.append(
@@ -292,12 +276,12 @@ if __name__ == "__main__":
         action="store_true",
     )
     parser.add_argument(
-        "-e",
-        "--event",
-        help="The GitHub event name that triggered the workflow (e.g. 'push', "
-        "'pull_request'). Configs are filtered by their 'event_type'. If "
-        "omitted, no filtering is applied.",
-        default=None,
+        "-m",
+        "--minimal",
+        help="Emit only the minimal matrix (the configs flagged 'minimal'), "
+        "used for pull requests by default. If omitted, the full matrix is "
+        "emitted.",
+        action="store_true",
     )
     args = parser.parse_args()
 
@@ -308,15 +292,15 @@ if __name__ == "__main__":
     else:
         if args.config in ("linux", None):
             matrix += expand_linux_matrix(
-                LinuxFile.load(THIS_DIR / "linux.json"), args.event
+                LinuxFile.load(THIS_DIR / "linux.json"), args.minimal
             )
         if args.config in ("macos", None):
             matrix += expand_platform_matrix(
-                PlatformFile.load(THIS_DIR / "macos.json"), args.event
+                PlatformFile.load(THIS_DIR / "macos.json"), args.minimal
             )
         if args.config in ("windows", None):
             matrix += expand_platform_matrix(
-                PlatformFile.load(THIS_DIR / "windows.json"), args.event
+                PlatformFile.load(THIS_DIR / "windows.json"), args.minimal
             )
 
     print(f"matrix={json.dumps({'include': [dataclasses.asdict(e) for e in matrix]})}")

.github/scripts/strategy-matrix/linux.json

@@ -1,17 +1,31 @@
 {
-  "image_tag": "sha-e29b523",
+  "image_tag": "sha-3122de8",
   "configs": {
     "ubuntu": [
+      {
+        "compiler": ["clang"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": true
+      },
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false
+      },
       {
         "compiler": ["gcc", "clang"],
         "build_type": ["Debug", "Release"],
-        "arch": ["amd64", "arm64"]
+        "arch": ["arm64"],
+        "minimal": false
       },
 
       {
         "compiler": ["gcc", "clang"],
         "build_type": ["Debug", "Release"],
         "arch": ["amd64"],
+        "minimal": false,
         "sanitizers": ["address", "undefinedbehavior"]
       },
 
@@ -19,6 +33,7 @@
         "compiler": ["gcc"],
         "build_type": ["Debug"],
         "arch": ["amd64"],
+        "minimal": true,
         "suffix": "coverage",
         "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=500 -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
       },
@@ -26,6 +41,7 @@
         "compiler": ["clang"],
         "build_type": ["Debug"],
         "arch": ["amd64"],
+        "minimal": false,
         "suffix": "voidstar",
         "extra_cmake_args": "-Dvoidstar=ON"
       },
@@ -33,6 +49,7 @@
         "compiler": ["clang"],
         "build_type": ["Release"],
         "arch": ["amd64"],
+        "minimal": false,
         "suffix": "reffee",
         "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=1000"
       },
@@ -40,9 +57,9 @@
         "compiler": ["gcc"],
         "build_type": ["Debug"],
         "arch": ["amd64"],
+        "minimal": false,
         "suffix": "unity",
-        "extra_cmake_args": "-Dunity=ON",
-        "exclude_event_types": ["pull_request"]
+        "extra_cmake_args": "-Dunity=ON"
       }
     ],
 
@@ -50,7 +67,8 @@
       {
         "compiler": ["gcc"],
         "build_type": ["Release"],
-        "arch": ["amd64"]
+        "arch": ["amd64"],
+        "minimal": false
       }
     ],
 
@@ -58,7 +76,8 @@
       {
         "compiler": ["gcc"],
         "build_type": ["Release"],
-        "arch": ["amd64"]
+        "arch": ["amd64"],
+        "minimal": false
       }
     ]
   },
@@ -68,6 +87,7 @@
         "compiler": ["gcc"],
         "build_type": ["Release"],
         "arch": ["amd64"],
+        "minimal": false,
         "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-577d745"
       }
     ],
@@ -77,6 +97,7 @@
         "compiler": ["gcc"],
         "build_type": ["Release"],
         "arch": ["amd64"],
+        "minimal": false,
         "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-577d745"
       }
     ]

.github/scripts/strategy-matrix/macos.json

@@ -4,13 +4,14 @@
   "configs": [
     {
       "build_type": "Release",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5"
+      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
+      "minimal": true
     },
     {
       "build_type": "Debug",
       "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
       "build_only": true,
-      "exclude_event_types": ["pull_request"]
+      "minimal": false
     }
   ]
 }

.github/scripts/strategy-matrix/windows.json

@@ -2,11 +2,11 @@
   "platform": "windows/amd64",
   "runner": ["self-hosted", "Windows", "dev-box-windows-2026"],
   "configs": [
-    { "build_type": "Release" },
+    { "build_type": "Release", "minimal": true },
     {
       "build_type": "Debug",
       "build_only": true,
-      "exclude_event_types": ["pull_request"]
+      "minimal": false
     }
   ]
 }

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

@@ -1,4 +1,4 @@
-name: Build Nix Docker images
+name: Build `nix` Docker images
 
 on:
   push:
@@ -8,6 +8,7 @@ on:
       - ".github/workflows/build-nix-images.yml"
       - "flake.nix"
       - "flake.lock"
+      - "rust-toolchain.toml"
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
@@ -18,6 +19,7 @@ on:
       - ".github/workflows/build-nix-images.yml"
       - "flake.nix"
       - "flake.lock"
+      - "rust-toolchain.toml"
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
@@ -36,7 +38,7 @@ defaults:
 
 jobs:
   build-merge:
-    name: Build and push nix-${{ matrix.distro.name }}
+    name: Build and push `nix-${{ matrix.distro.name }}` image
     permissions:
       contents: read
       packages: write
@@ -54,7 +56,7 @@ jobs:
             base_image: debian:bookworm
           - name: rhel
             base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@ee03d31bcc4501d7599dc1b1ecd7a34af582ad1c
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/nix-${{ matrix.distro.name }}
       dockerfile: nix/docker/Dockerfile

.github/workflows/build-packaging-images.yml

@@ -1,4 +1,4 @@
-name: Build packaging Docker images
+name: Build `packaging` Docker images
 
 on:
   push:
@@ -26,7 +26,7 @@ defaults:
 
 jobs:
   build-merge:
-    name: Build and push packaging-${{ matrix.distro.name }}
+    name: Build and push `packaging-${{ matrix.distro.name }}` image
     permissions:
       contents: read
       packages: write
@@ -38,7 +38,7 @@ jobs:
             base_image: debian:bookworm
           - name: rhel
             base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@ee03d31bcc4501d7599dc1b1ecd7a34af582ad1c
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/packaging-${{ matrix.distro.name }}
       dockerfile: package/Dockerfile

.github/workflows/build-pre-commit-image.yml

@@ -0,0 +1,38 @@
+name: Build `pre-commit` Docker image
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - ".github/workflows/build-pre-commit-image.yml"
+      - "bin/pre-commit/Dockerfile"
+      - "rust-toolchain.toml"
+  pull_request:
+    paths:
+      - ".github/workflows/build-pre-commit-image.yml"
+      - "bin/pre-commit/Dockerfile"
+      - "rust-toolchain.toml"
+  workflow_dispatch:
+
+concurrency:
+  # Read `on-trigger.yml` for the rationale behind this concurrency group name.
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' && github.sha || github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-merge:
+    name: Build and push `pre-commit` image
+    permissions:
+      contents: read
+      packages: write
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
+    with:
+      image_name: xrpld/pre-commit
+      dockerfile: bin/pre-commit/Dockerfile
+      base_image: ubuntu:26.04
+      push: ${{ github.event_name == 'push' }}

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

@@ -20,4 +20,4 @@ on:
 jobs:
   check_title:
     if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81
+    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@d7c65e49225a38f6d8010eacf017bb5a98d7476c

.github/workflows/conflicting-pr.yml

@@ -14,6 +14,7 @@ permissions:
 
 jobs:
   main:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'IgnoreConflicts') }}
     runs-on: ubuntu-latest
     steps:
       - name: Check if PRs are dirty

.github/workflows/on-pr.yml

@@ -1,7 +1,11 @@
-# This workflow runs all workflows to check, build and test the project on
-# various Linux flavors, as well as on MacOS and Windows, on every push to a
-# user branch. However, it will not run if the pull request is a draft unless it
-# has the 'DraftRunCI' label. For commits to PRs that target a release branch,
+# This workflow runs workflows to check, build and test the project
+# on every meaningful change on pull_request.
+# However, it will not run if the PR is a draft
+# unless it has the 'DraftRunCI' or 'Full CI build' label.
+#
+# By default a PR builds only a minimal matrix.
+# The full matrix runs once the PR is labeled "Ready to merge" or "Full CI build".
+# For commits to PRs that target a release branch,
 # it also uploads the libxrpl recipe to the Conan remote.
 name: PR
 
@@ -15,8 +19,16 @@ on:
       - reopened
       - synchronize
       - ready_for_review
+      # Trigger on label changes so toggling "Ready to merge" or "Full CI build"
+      # switches between the minimal and full matrix without needing a new push.
+      - labeled
+      - unlabeled
 
 concurrency:
+  # A single per-ref group with cancel-in-progress means any newer run (a push
+  # or a label change) supersedes the in-progress one for that ref. Keeping
+  # exactly one authoritative run per ref ensures a fast do-nothing run can never
+  # mask a real build's checks.
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
@@ -25,11 +37,18 @@ defaults:
     shell: bash
 
 jobs:
-  # This job determines whether the rest of the workflow should run. It runs
-  # when the PR is not a draft (which should also cover merge-group) or
-  # has the 'DraftRunCI' label.
+  # This job determines whether the rest of the workflow should run at all,
+  # based on the current set of labels: it runs when the PR is not a draft
+  # (which should also cover merge-group) or has the 'DraftRunCI' or
+  # 'Full CI build' label. Whether a build then happens, and whether it is the
+  # minimal or full matrix, is decided further below and in the strategy matrix.
   should-run:
-    if: ${{ !github.event.pull_request.draft || contains(github.event.pull_request.labels.*.name, 'DraftRunCI') }}
+    if: >-
+      ${{
+        !github.event.pull_request.draft
+        || contains(github.event.pull_request.labels.*.name, 'DraftRunCI')
+        || contains(github.event.pull_request.labels.*.name, 'Full CI build')
+      }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -91,15 +110,17 @@ jobs:
         # least one of:
         # * Any of the files checked in the `changes` step were modified
         # * The PR is NOT a draft and is labeled "Ready to merge"
+        # * The PR is labeled "Full CI build" (draft or not)
         # * The workflow is running from the merge queue
         id: go
         env:
           FILES: ${{ steps.changes.outputs.any_changed }}
           DRAFT: ${{ github.event.pull_request.draft }}
           READY: ${{ contains(github.event.pull_request.labels.*.name, 'Ready to merge') }}
+          FULL: ${{ contains(github.event.pull_request.labels.*.name, 'Full CI build') }}
           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.FULL == 'true' || env.FILES == 'true' || env.MERGE == 'true' }}" >>"${GITHUB_OUTPUT}"
           cat "${GITHUB_OUTPUT}"
     outputs:
       go: ${{ steps.go.outputs.go == 'true' }}
@@ -142,7 +163,10 @@ jobs:
 
   package:
     needs: [should-run, build-test]
-    if: ${{ needs.should-run.outputs.go == 'true' }}
+    # Packaging consumes the debian/rhel release binaries, which are only built
+    # by the full matrix. Skip it for pull requests that ran only the minimal
+    # matrix (i.e. not yet labeled "Ready to merge" or "Full CI build").
+    if: ${{ needs.should-run.outputs.go == 'true' && (github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'Ready to merge') || contains(github.event.pull_request.labels.*.name, 'Full CI build')) }}
     uses: ./.github/workflows/reusable-package.yml
 
   upload-recipe:

.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@1bde119a1ab71305ba5d3716e7a82cea1c7bdede
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@3ba08d6ddf114092891d48491fc2e26c3ba15552
     with:
       runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'
+      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-f56b79f" }'

.github/workflows/publish-docs.yml

@@ -41,13 +41,13 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-e29b523
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3122de8
     steps:
       - name: Checkout repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@64ec3cf3b152b4444638f470bbd6df7a7a30c81c
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
         with:
           enable_ccache: false
 

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

@@ -113,7 +113,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@64ec3cf3b152b4444638f470bbd6df7a7a30c81c
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
         with:
           enable_ccache: ${{ inputs.ccache_enabled }}
 
@@ -124,7 +124,7 @@ jobs:
       - name: Check tools
         env:
           CHECK_TOOLS_SKIP_CLONE: "1"
-        run: ./bin/check-tools.sh
+        run: ./bin/check-tools.sh || true
 
       - name: Print build environment
         uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
@@ -223,11 +223,13 @@ jobs:
           BUILD_TYPE: ${{ inputs.build_type }}
           CMAKE_TARGET: ${{ inputs.cmake_target }}
         run: |
+          set -o pipefail
           cmake \
               --build . \
               --config "${BUILD_TYPE}" \
               --parallel "${BUILD_NPROC}" \
-              --target "${CMAKE_TARGET}"
+              --target "${CMAKE_TARGET}" \
+              2>&1 | tee "${GITHUB_WORKSPACE}/build.log"
 
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
@@ -322,27 +324,46 @@ jobs:
               PRELOAD=""
           fi
 
-          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee unittest.log
+          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"
 
-      - name: Show test failure summary
-        if: ${{ failure() && !inputs.build_only }}
-        env:
-          WORKING_DIR: ${{ runner.os == 'Windows' && format('{0}\{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
+      # Smoke-run every benchmark module with a single repetition to confirm the
+      # benchmarks still build and execute. This is a correctness check, not a
+      # performance measurement, so it is skipped for instrumented builds
+      # (sanitizers/coverage/voidstar), where it would be slow and meaningless,
+      # and on Windows, where the `install` target does not build them.
+      - name: Run the benchmarks
+        if: ${{ !inputs.build_only && runner.os != 'Windows' && env.SANITIZERS_ENABLED == 'false' && env.COVERAGE_ENABLED != 'true' && env.VOIDSTAR_ENABLED != 'true' }}
+        working-directory: ${{ env.BUILD_DIR }}
         run: |
-          if [ ! -d "${WORKING_DIR}" ]; then
-              echo "Working directory '${WORKING_DIR}' does not exist."
-              exit 0
-          fi
+          rc=0
+          while IFS= read -r bench; do
+              echo "::group::${bench}"
+              "./${bench}" --benchmark_repetitions=1 || rc=1
+              echo "::endgroup::"
+          done < <(find src/benchmarks -type f -perm -u+x -name 'xrpl.bench.*')
+          exit "${rc}"
 
-          cd "${WORKING_DIR}"
+      - name: Show build/test failure summary
+        if: ${{ failure() }}
+        run: |
+          cd "${GITHUB_WORKSPACE}"
 
-          if [ ! -f unittest.log ]; then
-              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."
+          if [ -f unittest.log ]; then
+              if ! grep -E "failed" unittest.log | grep -vE "^I[0-9]|^[0-9]+> (ERR:|FTL:)"; then
+                  echo "unittest.log present but no failure lines found."
+              fi
+          elif [ -f build.log ]; then
+              # GCC/Clang emit "error:" (covers "fatal error:"); MSVC emits
+              # "error C####:", "error LNK####:", and "fatal error LNK####:".
+              # -A6 prints the lines that follow each match (source line, caret,
+              # notes, and the "N errors generated" tally) to capture the whole
+              # diagnostic block.
+              if ! grep -E -A6 "error:|error C[0-9]{4}|error LNK[0-9]{4}|fatal error" build.log; then
+                  echo "build.log present but no compile errors found."
+              fi
+          else
+              echo "unittest.log/build.log not found; something went wrong."
+              exit 1
           fi
       - name: Debug failure (Linux)
         if: ${{ failure() && runner.os == 'Linux' && !inputs.build_only }}

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

@@ -34,7 +34,7 @@ jobs:
     needs: [determine-files]
     if: ${{ needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.need_full_run == 'true' }}
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-e29b523"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-3122de8"
     permissions:
       contents: read
       issues: write
@@ -43,7 +43,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@64ec3cf3b152b4444638f470bbd6df7a7a30c81c
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
         with:
           enable_ccache: false
 

.github/workflows/reusable-package.yml

@@ -30,7 +30,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
 

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

@@ -26,7 +26,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
 
@@ -35,5 +35,8 @@ jobs:
         id: generate
         env:
           GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}', inputs.os) || '' }}
-          GENERATE_EVENT: ${{ github.event_name }}
-        run: ./generate.py ${GENERATE_CONFIG} --event="${GENERATE_EVENT}" >>"${GITHUB_OUTPUT}"
+          # Run only the minimal matrix for pull requests that are not yet
+          # labeled "Ready to merge" or "Full CI build". Any other event (merge
+          # queue, push, schedule, manual dispatch) runs the full matrix.
+          GENERATE_MINIMAL: ${{ (github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'Ready to merge') && !contains(github.event.pull_request.labels.*.name, 'Full CI build')) && '--minimal' || '' }}
+        run: ./generate.py ${GENERATE_CONFIG} ${GENERATE_MINIMAL} >>"${GITHUB_OUTPUT}"

.github/workflows/reusable-upload-recipe.yml

@@ -40,7 +40,7 @@ defaults:
 jobs:
   upload:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-e29b523
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3122de8
     env:
       REMOTE_NAME: ${{ inputs.remote_name }}
       CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}

.github/workflows/upload-conan-deps.yml

@@ -68,7 +68,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@64ec3cf3b152b4444638f470bbd6df7a7a30c81c
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
         with:
           enable_ccache: false
 

.gitignore

@@ -81,6 +81,9 @@ DerivedData
 # Python
 __pycache__
 
+# Rust build artifacts.
+target/
+
 # Direnv's directory
 /.direnv
 

.pre-commit-config.yaml

@@ -32,6 +32,11 @@ repos:
         # as standalone translation units, so they have no compile_commands.json
         # entry to lint (verify_headers checks them transitively).
         exclude: '^include/xrpl/protocol_autogen|\.ipp$'
+        # run-clang-tidy --fix may edit headers included by files it is not run on,
+        # so pre-commit must not split the files across parallel hook invocations.
+        # The script determines the staged files itself and lets run-clang-tidy
+        # handle parallelism internally.
+        pass_filenames: false
       - id: fix-include-style
         name: fix include style
         entry: ./bin/pre-commit/fix_include_style.py
@@ -50,7 +55,7 @@ repos:
         types_or: [c++, c]
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: dd18dad857d6133e90bbe478f4f2f22ec0030269 # frozen: v22.1.5
+    rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
     hooks:
       - id: clang-format
         args: [--style=file]
@@ -63,7 +68,7 @@ repos:
       - id: gersemi
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: 39e2973981e6d2f9b6c543b0086a2d2393abdc89 # frozen: v3.9.4
+    rev: 9337a74165b178ae2c766f60bee7252a0f06f3e8 # frozen: v3.9.5
     hooks:
       - id: prettier
         args: [--end-of-line=auto]

API-CHANGELOG.md

@@ -28,6 +28,9 @@ This section contains changes targeting a future version.
 
 ### Additions
 
+- `account_tx`: Added an optional `delegate` request object to filter delegated transactions. The object requires `delegate_filter`, which must be either `actor` for transactions owned by the requested account but signed by another account, or `authorizer` for transactions signed by the requested account on behalf of another account. The optional `counter_party` account narrows the results to a specific signer/delegate for `actor` or a specific owner/delegator for `authorizer`. Malformed `delegate`, `delegate_filter`, and `counter_party` values return standard invalid field errors, and invalid account IDs return `actMalformed`.
+  When paginating delegate-filtered queries, a marker from a delegate-filtered query includes a `delegate` flag and is only valid for follow-up requests that also supply `delegate` (mixing marker conventions returns `invalidParams`). Because filtering is applied after the ledger scan, a page may contain fewer results than `limit` (possibly zero) while still returning a marker, so callers must continue until no marker is present.
+
 - `ledger_entry`, `account_objects`: The `Delegate` ledger entry now includes an optional `DestinationNode` field, which stores the index into the authorized account's owner directory. This field is present on entries created after bidirectional directory tracking was introduced and may appear in RPC responses for those entries. ([#6681](https://github.com/XRPLF/rippled/pull/6681))
 
 - `server_definitions`: Added the following new sections to the response ([#6321](https://github.com/XRPLF/rippled/pull/6321)):

CMakeLists.txt

@@ -96,6 +96,7 @@ find_package(OpenSSL REQUIRED)
 find_package(secp256k1 REQUIRED)
 find_package(SOCI REQUIRED)
 find_package(SQLite3 REQUIRED)
+find_package(wasmi REQUIRED)
 find_package(xxHash REQUIRED)
 
 target_link_libraries(
@@ -131,6 +132,10 @@ else()
 endif()
 target_link_libraries(xrpl_libs INTERFACE ${nudb})
 
+if(benchmark)
+    find_package(benchmark REQUIRED)
+endif()
+
 if(coverage)
     include(XrplCov)
 endif()
@@ -145,3 +150,7 @@ if(tests)
     include(CTest)
     add_subdirectory(src/tests/libxrpl)
 endif()
+
+if(benchmark)
+    add_subdirectory(src/benchmarks/libxrpl)
+endif()

CODEOWNERS

@@ -0,0 +1,4 @@
+# By default, anyone can review changes.
+
+# The CI tooling team should review changes to the CI configuration.
+/.github/ @XRPLF/ci-tooling

CONTRIBUTING.md

@@ -83,8 +83,11 @@ If you create new source files, they must be organized as follows:
   `src/libxrpl`.
 - All other non-test files must go under `src/xrpld`.
 - All test source files must go under `src/test`.
+- All benchmark source files must go under `src/benchmarks`.
 
-The source must be formatted according to the style guide below.
+The source must be formatted according to the style guide below. The easiest
+way to satisfy this is to install the [`pre-commit`](#pre-commit-hooks) hooks,
+which format and lint your changes automatically on every commit.
 
 Header includes must be [levelized](.github/scripts/levelization).
 
@@ -212,13 +215,61 @@ This is a non-exhaustive list of recommended style guidelines. These are
 not always strictly enforced and serve as a way to keep the codebase
 coherent rather than a set of _thou shalt not_ commandments.
 
+## Pre-commit hooks
+
+We use the [`pre-commit`](https://pre-commit.com/) framework to run the
+formatting and linting tools that keep the codebase consistent. `pre-commit`
+runs each tool configured in
+[`.pre-commit-config.yaml`](./.pre-commit-config.yaml) in its own isolated
+environment, so you don't need to install most of the individual tools
+yourself. The version of each hook sourced from an external repository
+(`clang-format`, `gersemi`, etc.) is pinned in that file, so running the hooks
+locally uses exactly the same versions as CI. A few `local` hooks — most notably
+`clang-tidy` — run tools from your own environment; see
+[Installing clang-tidy](#installing-clang-tidy) for how to get those.
+
+To get started, install `pre-commit` and enable the git hook scripts:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+Once installed, the hooks run automatically on your staged files every time you
+`git commit`. You can also run them on demand:
+
+```bash
+# Run all hooks against only the staged files
+pre-commit run
+
+# Run all hooks against every file in the repository
+pre-commit run --all-files
+
+# Run a single hook (e.g. clang-format) against all files
+pre-commit run clang-format --all-files
+```
+
+The hooks configured in this repository include, among others:
+
+- `clang-format` — C++/proto formatting (see [Formatting](#formatting))
+- `clang-tidy` — C++ static analysis (see [Clang-tidy](#clang-tidy)); opt in with `TIDY=1`
+- `fix-include-style`, `fix-pragma-once`, `check-doxygen-style` — C++ hygiene
+- `gersemi` — CMake formatting
+- `prettier`, `black`, `shfmt` — formatting for JavaScript/JSON/Markdown, Python, and shell
+- `cspell` — spell checking
+
+The same hooks run in CI on every pull request, so running them locally before
+you push helps you avoid CI failures.
+
 ## Formatting
 
-All code must conform to `clang-format` version 22,
-according to the settings in [`.clang-format`](./.clang-format),
-unless the result would be unreasonably difficult to read or maintain.
-To demarcate lines that should be left as-is, surround them with comments like
-this:
+All code must conform to `clang-format`, according to the settings in
+[`.clang-format`](./.clang-format), unless the result would be unreasonably
+difficult to read or maintain. The `clang-format` version is pinned in
+[`.pre-commit-config.yaml`](./.pre-commit-config.yaml), so the
+[`pre-commit`](#pre-commit-hooks) hook always formats with the same version as
+CI. To demarcate lines that should be left as-is, surround them with comments
+like this:
 
 ```
 // clang-format off
@@ -226,9 +277,21 @@ this:
 // clang-format on
 ```
 
-You can format individual files in place by running `clang-format -i <file>...`
+The easiest way to format your changes is to let the `pre-commit` hook run
+automatically on commit, or to run it manually:
+
+```bash
+pre-commit run clang-format --all-files
+```
+
+You can also format individual files in place by running `clang-format -i <file>...`
 from any directory within this project.
 
+> [!NOTE]
+> This uses whatever `clang-format` version is installed locally, which may
+> differ from the pinned version used by `pre-commit` and CI, so the results
+> can vary.
+
 There is a Continuous Integration job that runs clang-format on pull requests. If the code doesn't comply, a patch file that corrects auto-fixable formatting issues is generated.
 
 To download the patch file:
@@ -239,13 +302,6 @@ To download the patch file:
 4. Download the zip file and extract it to your local git repository. Run `git apply [patch-file-name]`.
 5. Commit and push.
 
-You can install a pre-commit hook to automatically run `clang-format` before every commit:
-
-```
-pip3 install pre-commit
-pre-commit install
-```
-
 ## Clang-tidy
 
 All code must pass `clang-tidy` checks according to the settings in [`.clang-tidy`](./.clang-tidy).
@@ -267,7 +323,7 @@ Before running clang-tidy, you must build the project to generate required files
 
 #### Via pre-commit (recommended)
 
-If you have already installed the pre-commit hooks (see above), you can run clang-tidy on your staged files using:
+If you have already installed the [`pre-commit`](#pre-commit-hooks) hooks, you can run clang-tidy on your staged files using:
 
 ```
 TIDY=1 pre-commit run clang-tidy

bin/check-tools.sh

@@ -110,6 +110,23 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     fi
 fi
 
+# Rust toolchain. Part of the Nix commonPackages, so available on both Linux
+# and macOS. The cargo plugins are invoked through cargo (`cargo <sub>`), which
+# resolves the matching `cargo-<sub>` binary on PATH; `--version` is offline and
+# does not need a Cargo project.
+if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
+    echo
+    echo "Rust toolchain:"
+    check cargo
+    check cargo-audit cargo audit --version
+    check cargo-llvm-cov cargo llvm-cov --version
+    check cargo-nextest cargo nextest --version
+    check clippy clippy-driver --version
+    check rust-analyzer
+    check rustc
+    check rustfmt
+fi
+
 # GCC is the default compiler on Linux. macOS uses the system Apple Clang
 # instead, so GCC/g++/gcov are not expected there.
 if [ "${os}" = "linux" ]; then

bin/pre-commit/Dockerfile

@@ -0,0 +1,55 @@
+ARG BASE_IMAGE=ubuntu:26.04
+
+FROM ${BASE_IMAGE}
+
+SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
+ENTRYPOINT ["/bin/bash"]
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+RUN <<EOF
+pkgs=()
+pkgs+=(curl)         # Required to install nix.
+pkgs+=(doxygen)      # Needed for Clio's check-doxygen-docs.sh.
+pkgs+=(git)          # Required for prepare-runner.
+pkgs+=(libatomic1)   # Required to run pre-commit provided `node`.
+pkgs+=(python3)      # Python 3 interpreter.
+pkgs+=(python3-pip)  # Package manager for Python applications.
+pkgs+=(xz-utils)     # Required to install nix
+
+apt-get update
+apt-get install -y --no-install-recommends "${pkgs[@]}"
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+EOF
+
+ARG PRE_COMMIT_VERSION=4.6.0
+RUN pip install --no-cache --break-system-packages \
+    pre-commit==${PRE_COMMIT_VERSION}
+
+RUN sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon --yes
+
+# Add nix to PATH and set NIX environment variables,
+# so nix is available in all shells including non-interactive shells (e.g., GitHub Actions).
+ENV PATH="/nix/var/nix/profiles/default/bin:${PATH}"
+ENV NIX_PROFILES="/nix/var/nix/profiles/default"
+ENV NIX_SSL_CERT_FILE="/nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt"
+
+# Verify nix installation
+RUN nix --version
+
+ENV RUSTUP_HOME="/opt/rust/rustup"
+ENV CARGO_HOME="/opt/rust/cargo"
+ENV PATH="/opt/rust/cargo/bin:${PATH}"
+
+WORKDIR /tmp
+COPY rust-toolchain.toml /tmp/rust-toolchain.toml
+RUN <<EOF
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal --default-toolchain none
+rustup toolchain install
+rustup show
+cargo fmt --version
+EOF
+
+WORKDIR /

bin/pre-commit/clang_tidy_check.py

@@ -1,27 +1,46 @@
 #!/usr/bin/env python3
-"""Pre-commit hook that runs clang-tidy on changed files using run-clang-tidy.
+"""Pre-commit hook that runs clang-tidy on staged files using run-clang-tidy.
 
-The set of files is chosen by pre-commit (see .pre-commit-config.yaml), which
-filters to C/C++ sources and excludes `.ipp` fragments. Headers are linted
-directly: the `verify_headers` build option (ON by default) compiles every
-`.h`/`.hpp` on its own, so each header is the main file of its own
-compile_commands.json entry and run-clang-tidy can analyse it just like a
-`.cpp`.
+The script determines the staged files itself (see `pass_filenames: false` in
+.pre-commit-config.yaml) so run-clang-tidy is run once and handles parallelism
+internally: pre-commit would otherwise split the files across parallel hook
+invocations that race when fixes edit a shared header.
+
+Fixes are collected with `-export-fixes` and applied by clang-apply-replacements
+in a separate step rather than with run-clang-tidy's `-fix`. The `add_module`
+build isolates each module's headers behind a per-module symlink directory
+(build/modules/<module>/...), so a header reachable from several translation
+units is referenced through different paths that all resolve to the same source
+file. clang-apply-replacements deduplicates identical replacements by their
+literal path, so those paths must be canonicalised to the real source path
+first; otherwise the same fix is applied once per path and corrupts the header.
 """
 
 from __future__ import annotations
 
 import os
+import re
 import shutil
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 CLANG_TIDY_VERSION = 22
 
+# Extensions run-clang-tidy can analyse: `.cpp` translation units and, thanks to
+# the `verify_headers` build option, `.h`/`.hpp` headers (each has its own
+# compile_commands.json entry). `.ipp` fragments have no entry and are skipped.
+TIDY_EXTENSIONS = {".cpp", ".h", ".hpp"}
 
-def find_run_clang_tidy() -> str | None:
-    for candidate in (f"run-clang-tidy-{CLANG_TIDY_VERSION}", "run-clang-tidy"):
+# A single-quoted `FilePath:` entry in an -export-fixes YAML file, allowing the
+# `- ` marker that precedes it inside a `Replacements:` sequence. clang-tidy
+# emits paths single-quoted and doubles any embedded quote per YAML rules.
+FILEPATH_RE = re.compile(r"^(\s*(?:-\s+)?FilePath:\s*)'((?:[^']|'')*)'\s*$")
+
+
+def find_tool(name: str) -> str | None:
+    for candidate in (f"{name}-{CLANG_TIDY_VERSION}", name):
         if path := shutil.which(candidate):
             return path
     return None
@@ -35,23 +54,43 @@ def find_build_dir(repo_root: Path) -> Path | None:
     return None
 
 
+def staged_files(repo_root: Path) -> list[Path]:
+    """Return absolute paths of staged, lint-able C/C++ files.
+
+    `--diff-filter=d` excludes deletions so we never lint a removed file.
+    """
+    output = subprocess.check_output(
+        ["git", "diff", "--staged", "--name-only", "--diff-filter=d", "--"]
+        + [f"*{ext}" for ext in TIDY_EXTENSIONS],
+        text=True,
+        cwd=repo_root,
+    )
+    return [repo_root / rel for rel in output.splitlines() if rel]
+
+
+def canonicalize_fix_paths(fixes_dir: Path) -> None:
+    """Rewrite every `FilePath` in the exported fixes to its real source path.
+
+    A header included through a module's isolation symlink is recorded under that
+    symlink's path; collapsing all paths to the same real file lets
+    clang-apply-replacements recognise the per-translation-unit duplicates and
+    apply each fix once.
+    """
+    for yaml in fixes_dir.glob("*.yaml"):
+        lines = []
+        for line in yaml.read_text().splitlines():
+            if m := FILEPATH_RE.match(line):
+                path = m.group(2).replace("''", "'")
+                real = os.path.realpath(path).replace("'", "''")
+                line = f"{m.group(1)}'{real}'"
+            lines.append(line)
+        yaml.write_text("\n".join(lines) + "\n")
+
+
 def main():
     if not os.environ.get("TIDY"):
         return 0
 
-    files = sys.argv[1:]
-    if not files:
-        return 0
-
-    run_clang_tidy = find_run_clang_tidy()
-    if not run_clang_tidy:
-        print(
-            f"clang-tidy check failed: TIDY is enabled but neither "
-            f"'run-clang-tidy-{CLANG_TIDY_VERSION}' nor 'run-clang-tidy' was found in PATH.",
-            file=sys.stderr,
-        )
-        return 1
-
     repo_root = Path(
         subprocess.check_output(
             ["git", "rev-parse", "--show-toplevel"],
@@ -59,6 +98,29 @@ def main():
             text=True,
         ).strip()
     )
+
+    files = staged_files(repo_root)
+    if not files:
+        return 0
+
+    run_clang_tidy = find_tool("run-clang-tidy")
+    clang_apply_replacements = find_tool("clang-apply-replacements")
+    missing = [
+        name
+        for name, path in (
+            ("run-clang-tidy", run_clang_tidy),
+            ("clang-apply-replacements", clang_apply_replacements),
+        )
+        if not path
+    ]
+    if missing:
+        print(
+            f"clang-tidy check failed: TIDY is enabled but {' and '.join(missing)} "
+            f"was not found in PATH (tried the '-{CLANG_TIDY_VERSION}' suffix too).",
+            file=sys.stderr,
+        )
+        return 1
+
     build_dir = find_build_dir(repo_root)
     if not build_dir:
         print(
@@ -68,11 +130,23 @@ def main():
         )
         return 1
 
-    result = subprocess.run(
-        [run_clang_tidy, "-quiet", "-p", str(build_dir), "-fix", "-allow-no-checks"]
-        + files
-    )
-    return result.returncode
+    with tempfile.TemporaryDirectory() as fixes_dir:
+        result = subprocess.run(
+            [
+                run_clang_tidy,
+                "-quiet",
+                "-p",
+                build_dir,
+                "-export-fixes",
+                fixes_dir,
+                "-allow-no-checks",
+            ]
+            + files
+        )
+        canonicalize_fix_paths(Path(fixes_dir))
+        applied = subprocess.run([clang_apply_replacements, fixes_dir])
+
+    return result.returncode or applied.returncode
 
 
 if __name__ == "__main__":

cmake/XrplAddBenchmark.cmake

@@ -0,0 +1,36 @@
+include(isolate_headers)
+
+# Define a benchmark executable for the module `name`.
+#
+# This follows the same general pattern as other build helpers in this repo
+# (e.g. `add_module`): create a target and isolate headers, but here the target
+# is a benchmark executable and no `add_test(...)` is registered.
+#
+# `isolate_headers` exposes only `${CMAKE_CURRENT_SOURCE_DIR}/${name}` on the
+# include path, rooted at `src`, so a benchmark's own headers are reached as
+# `<benchmarks/.../${name}/...>` and nothing else in the tree leaks in.
+function(xrpl_add_benchmark name)
+    set(target ${PROJECT_NAME}.bench.${name})
+
+    file(
+        GLOB_RECURSE sources
+        CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}/*.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}.cpp"
+    )
+    add_executable(${target} ${ARGN} ${sources})
+
+    # Benchmark sources register cases through Google Benchmark's static
+    # registrars (anonymous-namespace lambdas). Merging several such files into
+    # one unity translation unit collides those internal-linkage entities, so
+    # keep benchmarks out of the unity build - mirroring xrpl.libpb in
+    # XrplCore.cmake. Each file compiles fine on its own.
+    set_target_properties(${target} PROPERTIES UNITY_BUILD OFF)
+
+    isolate_headers(
+        ${target}
+        "${CMAKE_SOURCE_DIR}/src"
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}"
+        PRIVATE
+    )
+endfunction()

cmake/XrplCore.cmake

@@ -67,6 +67,7 @@ target_link_libraries(
         Xrpl::opts
         Xrpl::syslibs
         secp256k1::secp256k1
+        wasmi::wasmi
         xrpl.libpb
         xxHash::xxhash
         $<$<BOOL:${voidstar}>:antithesis-sdk-cpp>

cmake/XrplSettings.cmake

@@ -30,6 +30,8 @@ if(tests)
     endif()
 endif()
 
+option(benchmark "Build benchmarks" ON)
+
 # Enabled by default so every header is compiled on its own as the main file of
 # its own compile_commands.json entry - this is what lets clang-tidy (and clangd
 # and IDEs) analyse a header's own includes directly. The per-header objects are

conan.lock

@@ -3,6 +3,7 @@
     "requires": [
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
         "xxhash/0.8.3#681d36a0a6111fc56e5e45ea182c19cc%1782392402.420688",
+        "wasmi/1.0.9#1fecdab9b90c96698eb35ea99ca4f5cb%1782307153.343419",
         "sqlite3/3.53.0#324ada52333108388a9a6108bfa96734%1782392403.185447",
         "soci/4.0.3#e726491a03468795453f7c83fc924a96%1782392402.679521",
         "snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1782307151.633168",
@@ -10,22 +11,23 @@
         "rocksdb/10.5.1#4a197eca381a3e5ae8adf8cffa5aacd0%1782392413.075713",
         "re2/20251105#8579cfd0bda4daf0683f9e3898f964b4%1782392402.431897",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "openssl/3.6.3#1163d4ddc603907084d08a6a0c6e580f%1782307150.583886",
+        "openssl/3.6.3#f806de8933e3bf6f01016c6a888cee2e%1783945160.863288",
         "nudb/2.0.9#11149c73f8f2baff9a0198fe25971fc7%1782392402.297166",
-        "mpt-crypto/0.4.0-rc2#a580f2f9ad0e795de696aa62d54fb9af%1782425834.488828",
+        "mpt-crypto/0.4.0-rc4#ffdba12f2332357f0d8b0ae944cfff52%1784138702.932355",
         "lz4/1.10.0#982d9b673900f665a1da109e09c17cab%1782392402.164188",
         "libiconv/1.17#9923bc6dc6f106646d6967e0039a5ada%1782392792.775744",
         "libbacktrace/cci.20210118#a7691bfccd8caaf66309df196790a5a1%1782392402.420732",
         "libarchive/3.8.7#c446109bd1f1d8ba7936c94189bc50e6%1782392403.066892",
         "jemalloc/5.3.1#1fc58d55316041f10fbc1e8a2eae632a%1776700028.228",
         "gtest/1.17.0#5224b3b3ff3b4ce1133cbdd27d53ee7d%1782392402.791979",
-        "grpc/1.81.1#5217e6ef0544c42b46f4af35d5e7f649%1782307148.845616",
+        "grpc/1.81.1#f729f6d75992d20f9c72828e9142d62f%1783945160.094135",
         "ed25519/2015.03#ae761bdc52730a843f0809bdf6c1b1f6%1782307148.15562",
         "date/3.0.4#862e11e80030356b53c2c38599ceb32b%1782392402.538492",
         "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1782392402.681654",
         "bzip2/1.0.8#c470882369c2d95c5c77e970c0c7e321%1782392402.296732",
         "boost/1.91.0#ea540ca2133d831b560036aa24dece3c%1782392419.475605",
-        "abseil/20250127.0#bb0baf1f362bc4a725a24eddd419b8f7%1782307147.395833"
+        "benchmark/1.9.5#b885dc73ad67b40a55d45684d1c88ad1%1782736613.864841",
+        "abseil/20250127.0#9ef01c1451a8340f9022e46238c0fbb6%1783945159.651047"
     ],
     "build_requires": [
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
@@ -38,7 +40,7 @@
         "b2/5.4.2#ffd6084a119587e70f11cd45d1a386e2%1782392402.624226",
         "automake/1.16.5#b91b7c384c3deaa9d535be02da14d04f%1755524470.56",
         "autoconf/2.71#51077f068e61700d65bb05541ea1e4b0%1731054366.86",
-        "abseil/20250127.0#bb0baf1f362bc4a725a24eddd419b8f7%1782307147.395833"
+        "abseil/20250127.0#9ef01c1451a8340f9022e46238c0fbb6%1783945159.651047"
     ],
     "python_requires": [],
     "overrides": {

conan/profiles/default

@@ -20,6 +20,22 @@ compiler.libcxx={{ detect_api.detect_libcxx(compiler, version, compiler_exe) }}
 {% endif %}
 
 [conf]
+{# The Boost recipe builds with b2, which doesn't use Conan's toolchain files. #}
+{# Instead it hand-rolls the compiler for user-config.jam, #}
+{# and its fallback probes a version-suffixed binary (e.g. `g++-15`) before plain `g++`. #}
+{# Inside the Nix shell the wrapper only provides `g++`/`gcc` (no `-15` suffix), #}
+{# so on a host that also has a system `g++-15` the probe escapes Nix #}
+{# and picks the system compiler, which is mismatched with the Nix libraries #}
+{# and breaks the build (e.g. Boost.Stacktrace link checks fail). #}
+{# Pinning the executables here short-circuits that probe so Boost (and the rest of the toolchain) #}
+{# resolve the same compiler. #}
+{# Not part of the package ID, so binaries stay shareable. #}
+{% if os != "Windows" %}
+{% set cc_exe  = {"gcc": "gcc",  "clang": "clang",   "apple-clang": "clang"}.get(compiler) %}
+{% set cxx_exe = {"gcc": "g++",  "clang": "clang++", "apple-clang": "clang++"}.get(compiler) %}
+tools.build:compiler_executables={'c':'{{ cc_exe }}','cpp':'{{ cxx_exe }}'}
+{% endif %}
+
 {# By default, Conan tries to reuse binaries built with different cppstd versions. #}
 {# We want to avoid that to improve reproduceability, so we add the cppstd version to the package ID. #}
 {# More info: https://docs.conan.io/2/reference/extensions/binary_compatibility.html #}

conanfile.py

@@ -15,6 +15,7 @@ class Xrpl(ConanFile):
     settings = "os", "compiler", "build_type", "arch"
     options = {
         "assertions": [True, False],
+        "benchmark": [True, False],
         "coverage": [True, False],
         "fPIC": [True, False],
         "jemalloc": [True, False],
@@ -33,6 +34,7 @@ class Xrpl(ConanFile):
         "nudb/2.0.9",
         "openssl/3.6.3",
         "soci/4.0.3",
+        "wasmi/1.0.9",
         "zlib/1.3.2",
     ]
 
@@ -46,6 +48,7 @@ class Xrpl(ConanFile):
 
     default_options = {
         "assertions": False,
+        "benchmark": True,
         "coverage": False,
         "fPIC": True,
         "jemalloc": False,
@@ -129,12 +132,14 @@ class Xrpl(ConanFile):
             self.options["boost"].without_cobalt = True
 
     def requirements(self):
+        if self.options.benchmark:
+            self.requires("benchmark/1.9.5")
         self.requires("boost/1.91.0", force=True, transitive_headers=True)
         self.requires("date/3.0.4", transitive_headers=True)
         if self.options.jemalloc:
             self.requires("jemalloc/5.3.1")
         self.requires("lz4/1.10.0", force=True)
-        self.requires("mpt-crypto/0.4.0-rc2", transitive_headers=True)
+        self.requires("mpt-crypto/0.4.0-rc4", transitive_headers=True)
         self.requires("protobuf/6.33.5", force=True)
         if self.options.rocksdb:
             self.requires("rocksdb/10.5.1")
@@ -162,6 +167,7 @@ class Xrpl(ConanFile):
     def generate(self):
         tc = CMakeToolchain(self)
         tc.variables["tests"] = self.options.tests
+        tc.variables["benchmark"] = self.options.benchmark
         tc.variables["assert"] = self.options.assertions
         tc.variables["coverage"] = self.options.coverage
         tc.variables["jemalloc"] = self.options.jemalloc
@@ -216,6 +222,7 @@ class Xrpl(ConanFile):
             "soci::soci",
             "secp256k1::secp256k1",
             "sqlite3::sqlite",
+            "wasmi::wasmi",
             "xxhash::xxhash",
             "zlib::zlib",
         ]

flake.lock

@@ -36,7 +36,28 @@
     "root": {
       "inputs": {
         "nixpkgs": "nixpkgs",
-        "nixpkgs-custom-glibc": "nixpkgs-custom-glibc"
+        "nixpkgs-custom-glibc": "nixpkgs-custom-glibc",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1784611586,
+        "narHash": "sha256-OfqgY+0hp/zseZB7uyH0U8kIDPS4scZZCyAurEplvG0=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "14f58845249f3552a89b07772626b8d3c632fa86",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
       }
     }
   },

flake.nix

@@ -10,12 +10,25 @@
       url = "github:NixOS/nixpkgs/9cd98386a38891d1074fc18036b842dc4416f562";
       flake = false;
     };
+    # Pinned Rust toolchains, delivered from the Nix store. Lets the Nix CI
+    # image and dev shell honour the single `rust-toolchain.toml` pin (shared
+    # with the rustup-based non-Nix runners) while staying hermetic — the
+    # toolchain lands in the image's Nix closure and is locked by flake.lock.
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
   };
 
   outputs =
-    { nixpkgs, nixpkgs-custom-glibc, ... }:
+    {
+      nixpkgs,
+      nixpkgs-custom-glibc,
+      rust-overlay,
+      ...
+    }:
     let
-      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-custom-glibc; };
+      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-custom-glibc rust-overlay; };
     in
     {
       devShells = forEachSystem (import ./nix/devshell.nix);

include/xrpl/basics/Number.h

@@ -364,6 +364,8 @@ public:
     static constexpr internalrep kMaxRep = std::numeric_limits<rep>::max();
     static_assert(kMaxRep == 9'223'372'036'854'775'807);
     static_assert(-kMaxRep == std::numeric_limits<rep>::min() + 1);
+    static constexpr internalrep kMaxRepUp = ((kMaxRep / 10) + 1) * 10;
+    static_assert(kMaxRepUp == 9'223'372'036'854'775'810ULL);
 
     // May need to make unchecked private
     struct Unchecked
@@ -547,8 +549,21 @@ public:
     setround(RoundingMode inMode);
 
     /**
-     * Returns which mantissa scale is currently in use for normalization.
+     * Convert an integer to a RoundingMode, validating that it is in range.
      *
+     * Returns std::nullopt if the value does not correspond to a valid
+     * RoundingMode.
+     */
+    static std::optional<RoundingMode>
+    checkedRoundingMode(int mode) noexcept
+    {
+        if (mode < static_cast<int>(RoundingMode::ToNearest) ||
+            mode > static_cast<int>(RoundingMode::Upward))
+            return std::nullopt;
+        return static_cast<RoundingMode>(mode);
+    }
+
+    /**
      * If you think you need to call this outside of unit tests, no you don't.
      */
     static MantissaRange::MantissaScale
@@ -591,6 +606,13 @@ public:
     std::pair<T, int>
     normalizeToRange() const;
 
+    // Safely convert rep (int64) mantissa to internalrep (uint64). If the rep
+    // is negative, returns the positive value. This takes a little extra work
+    // because converting std::numeric_limits<std::int64_t>::min() flirts with
+    // UB, and can vary across compilers.
+    static internalrep
+    externalToInternal(rep mantissa);
+
 private:
     static thread_local RoundingMode mode;
     // The available ranges for mantissa
@@ -645,13 +667,6 @@ private:
     // exponent could go out of range, so it will be checked.
     [[nodiscard]] Number
     shiftExponent(int exponentDelta) const;
-
-    // Safely convert rep (int64) mantissa to internalrep (uint64). If the rep
-    // is negative, returns the positive value. This takes a little extra work
-    // because converting std::numeric_limits<std::int64_t>::min() flirts with
-    // UB, and can vary across compilers.
-    static internalrep
-    externalToInternal(rep mantissa);
 };
 
 constexpr Number::Number(bool negative, internalrep mantissa, int exponent, Unchecked) noexcept

include/xrpl/basics/TaggedCache.ipp

@@ -3,6 +3,9 @@
 #include <xrpl/basics/IntrusivePointer.ipp>
 #include <xrpl/basics/Log.h>  // IWYU pragma: keep
 #include <xrpl/basics/TaggedCache.h>
+#include <xrpl/basics/scope.h>
+
+#include <algorithm>
 
 namespace xrpl {
 
@@ -601,8 +604,42 @@ TaggedCache<Key, T, IsKeyCache, SharedWeakUnionPointer, SharedPointerType, Hash,
     std::vector<key_type> v;
 
     {
-        std::scoped_lock const lock(mutex_);
-        v.reserve(cache_.size());
+        // Keep track of how many iterations are needed. Exit the loop if the number of retries gets
+        // absurd. (Note that if this somehow ever happens, one more allocation will be done under
+        // lock, which is undesirable, but really should be almost impossible.)
+        std::size_t allocationIterations = 0;
+        std::unique_lock lock(mutex_);
+        for (auto size = cache_.size(); v.capacity() < size && allocationIterations < 20;
+             size = cache_.size())
+        {
+            ScopeUnlock const unlock(lock);
+            if (allocationIterations > 0)
+            {
+                JLOG(journal_.info())
+                    << "getKeys(): Cache grew beyond allocated capacity after "
+                    << allocationIterations << " prior attempt(s). Have " << v.capacity()
+                    << ", need " << size << ". Retrying allocation";
+            }
+            // Allocate the current size plus a little extra, in case the cache grows while
+            // allocating. Each time another allocation is needed, the extra also gets bigger until
+            // it ultimately doubles the size + 1.
+            constexpr std::size_t baseShift = 5;
+            auto const bufferOffset = std::min(allocationIterations, std::size_t{baseShift});
+            auto const bufferShift = baseShift - bufferOffset;
+            size += (size >> bufferShift) + 1;
+            v.reserve(size);
+            ++allocationIterations;
+        }
+        if (v.capacity() < cache_.size())
+        {
+            // LCOV_EXCL_START
+            UNREACHABLE("xrpl::TaggedCache::getKeys(): failed to allocate sufficient capacity");
+            v.reserve(cache_.size());
+            // LCOV_EXCL_STOP
+        }
+        XRPL_ASSERT(lock.owns_lock(), "xrpl::TaggedCache::getKeys(): owns lock");
+        XRPL_ASSERT(
+            v.capacity() >= cache_.size(), "xrpl::TaggedCache::getKeys(): sufficient capacity");
         for (auto const& _ : cache_)
             v.push_back(_.first);
     }

include/xrpl/basics/base_uint.h

@@ -308,7 +308,9 @@ public:
         XRPL_ASSERT(
             c.size() * sizeof(typename Container::value_type) == size(),
             "xrpl::BaseUInt::fromRaw(Container auto) : input size match");
-        std::memcpy(result.data_.data(), c.data(), size());
+        std::size_t const canCopy =
+            std::min(size(), c.size() * sizeof(typename Container::value_type));
+        std::memcpy(result.data_.data(), c.data(), canCopy);
         return result;
     }
 
@@ -322,7 +324,11 @@ public:
         XRPL_ASSERT(
             c.size() * sizeof(typename Container::value_type) == size(),
             "xrpl::BaseUInt::operator=(Container auto) : input size match");
-        std::memcpy(data_.data(), c.data(), size());
+        std::size_t const canCopy =
+            std::min(size(), c.size() * sizeof(typename Container::value_type));
+        if (canCopy < size())
+            *this = beast::kZero;
+        std::memcpy(data_.data(), c.data(), canCopy);
         return *this;
     }
 

include/xrpl/beast/rfc2616.h

@@ -358,12 +358,13 @@ template <class = void>
 bool
 tokenInList(boost::string_ref const& value, boost::string_ref const& token)
 {
-    for (auto const& item : makeList(value))
-    {
-        if (ciEqual(item, token))
-            return true;
-    }
-    return false;
+    auto const list = makeList(value);
+    // ListIterator is not default-constructible, so it does not model a std::ranges
+    // sentinel/range; the classic std::any_of (which only needs an input iterator)
+    // is used instead.
+    // NOLINTNEXTLINE(modernize-use-ranges)
+    return std::any_of(
+        list.begin(), list.end(), [&token](auto const& item) { return ciEqual(item, token); });
 }
 
 template <bool IsRequest, class Body, class Fields>

include/xrpl/ledger/helpers/LendingHelpers.h

@@ -263,10 +263,11 @@ constructLoanState(
     Number const& principalOutstanding,
     Number const& managementFeeOutstanding);
 
-// Constructs a valid LoanState object from a Loan object, which always has
-// rounded values
+// Overload of constructLoanState() that reads the three tracked fields
+// directly from a Loan ledger object, which always holds rounded values,
+// rather than taking them as separate Number arguments.
 LoanState
-constructRoundedLoanState(SLE::const_ref loan);
+constructLoanState(SLE::const_ref loan);
 
 Number
 computeManagementFee(

include/xrpl/nodestore/DatabaseRotating.h

@@ -41,6 +41,19 @@ public:
         std::unique_ptr<NodeStore::Backend>&& newBackend,
         std::function<void(std::string const& writableName, std::string const& archiveName)> const&
             f) = 0;
+
+    /**
+     * Marks an online-delete rotation as in progress (or completed).
+     *
+     * While in flight, a read served by the archive backend is copied
+     * forward into the writable backend even for ordinary
+     * (duplicate == false) fetches: the archive is about to be deleted,
+     * and a node body canonicalized into caches during the rotation
+     * window would otherwise survive only in RAM once the archive is
+     * dropped.
+     */
+    virtual void
+    setRotationInFlight(bool inFlight) = 0;
 };
 
 }  // namespace xrpl::NodeStore

include/xrpl/nodestore/detail/DatabaseRotatingImp.h

@@ -9,6 +9,7 @@
 #include <xrpl/nodestore/NodeObject.h>
 #include <xrpl/nodestore/Scheduler.h>
 
+#include <atomic>
 #include <cstdint>
 #include <functional>
 #include <memory>
@@ -69,11 +70,22 @@ public:
     void
     sweep() override;
 
+    void
+    setRotationInFlight(bool inFlight) override;
+
 private:
     std::shared_ptr<Backend> writableBackend_;
     std::shared_ptr<Backend> archiveBackend_;
     mutable std::mutex mutex_;
 
+    // True between SHAMapStore starting the cache-freshen phase and the
+    // completion of rotate(). While true, archive hits on ordinary
+    // (duplicate == false) fetches are copied forward into the writable
+    // backend; copyForwardCount_ tallies them per rotation for the
+    // summary line logged at swap.
+    std::atomic<bool> rotationInFlight_{false};
+    std::atomic<std::uint64_t> copyForwardCount_{0};
+
     std::shared_ptr<NodeObject>
     fetchNodeObject(uint256 const& hash, std::uint32_t, FetchReport& fetchReport, bool duplicate)
         override;

include/xrpl/protocol/Indexes.h

@@ -13,7 +13,6 @@
 #include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/STXChainBridge.h>
 #include <xrpl/protocol/UintTypes.h>
-#include <xrpl/protocol/jss.h>
 
 #include <array>
 #include <cstdint>
@@ -423,21 +422,8 @@ struct KeyletDesc
     bool includeInTests{};
 };
 
-// This list should include all of the keylet functions that take a single
-// AccountID parameter.
-std::array<KeyletDesc<AccountID const&>, 6> const kDirectAccountKeylets{
-    {{.function = &keylet::account, .expectedLEName = jss::AccountRoot, .includeInTests = false},
-     {.function = &keylet::ownerDir, .expectedLEName = jss::DirectoryNode, .includeInTests = true},
-     {.function = &keylet::signerList, .expectedLEName = jss::SignerList, .includeInTests = true},
-     // It's normally impossible to create an item at nftpage_min, but
-     // test it anyway, since the invariant checks for it.
-     {.function = &keylet::nftokenPageMin,
-      .expectedLEName = jss::NFTokenPage,
-      .includeInTests = true},
-     {.function = &keylet::nftokenPageMax,
-      .expectedLEName = jss::NFTokenPage,
-      .includeInTests = true},
-     {.function = &keylet::did, .expectedLEName = jss::DID, .includeInTests = true}}};
+// This list should include all of the keylet functions that take a single AccountID parameter.
+extern std::array<KeyletDesc<AccountID const&>, 6> const kDirectAccountKeylets;
 
 MPTID
 makeMptID(std::uint32_t sequence, AccountID const& account);

include/xrpl/protocol/Protocol.h

@@ -322,6 +322,16 @@ constexpr std::uint8_t kVaultMaximumIouScale = 18;
  */
 constexpr std::uint8_t kMaxAssetCheckDepth = 5;
 
+/**
+ * Maximum length of a Data field in Escrow object that can be updated by WASM code.
+ */
+constexpr std::size_t kMaxWasmDataLength = 1 * 1024;  // 1KB
+
+/**
+ * Maximum amount of data transfer across hostfunction<->wasm border.
+ */
+constexpr std::size_t kWasmTransferLimit = 1 << 20;  // 1MB
+
 /**
  * A ledger index.
  */

include/xrpl/protocol/STObject.h

@@ -229,13 +229,6 @@ public:
     [[nodiscard]] AccountID
     getAccountID(SField const& field) const;
 
-    /**
-     * The account responsible for the authorization: the delegate when
-     * sfDelegate is present, otherwise the account.
-     */
-    [[nodiscard]] AccountID
-    getInitiator() const;
-
     [[nodiscard]] Blob
     getFieldVL(SField const& field) const;
     [[nodiscard]] STAmount const&

include/xrpl/protocol/STTx.h

@@ -142,9 +142,26 @@ public:
         TxnSql status,
         std::string const& escapedMetaData) const;
 
-    [[nodiscard]] std::vector<uint256> const&
+    /**
+     * The IDs of the inner transactions of a Batch.
+     */
+    [[nodiscard]] std::vector<uint256>
     getBatchTransactionIDs() const;
 
+    /**
+     * The inner transactions of a Batch, built and validated at construction.
+     * Always seated for Batch STTx instances (construction throws if oversized).
+     */
+    [[nodiscard]] std::vector<std::shared_ptr<STTx const>> const&
+    getBatchTransactions() const;
+
+    /**
+     * The account responsible for the authorization: the delegate when
+     * sfDelegate is present, otherwise the account.
+     */
+    [[nodiscard]] AccountID
+    getInitiator() const;
+
     [[nodiscard]] AccountID
     getFeePayerID() const;
 
@@ -166,13 +183,16 @@ private:
     checkMultiSign(Rules const& rules, STObject const& sigObject) const;
 
     [[nodiscard]] std::expected<void, std::string>
-    checkBatchSingleSign(STObject const& batchSigner) const;
+    checkBatchSingleSign(STObject const& batchSigner, std::vector<uint256> const& txIds) const;
 
     [[nodiscard]] std::expected<void, std::string>
-    checkBatchMultiSign(STObject const& batchSigner, Rules const& rules) const;
+    checkBatchMultiSign(
+        STObject const& batchSigner,
+        Rules const& rules,
+        std::vector<uint256> const& txIds) const;
 
     void
-    buildBatchTxnIds();
+    buildBatchTxns();
 
     STBase*
     copy(std::size_t n, void* buf) const override;
@@ -180,11 +200,11 @@ private:
     move(std::size_t n, void* buf) override;
 
     friend class detail::STVar;
-    std::optional<std::vector<uint256>> batchTxnIds_;
+    std::optional<std::vector<std::shared_ptr<STTx const>>> batchTxns_;
 };
 
 bool
-passesLocalChecks(STObject const& st, std::string&);
+passesLocalChecks(STTx const& tx, std::string&);
 
 /**
  * Sterilize a transaction.

include/xrpl/protocol/TER.h

@@ -129,8 +129,10 @@ enum TEMcodes : TERUnderlyingType {
     temARRAY_TOO_LARGE,
     temBAD_TRANSFER_FEE,
     temINVALID_INNER_BATCH,
+
     temBAD_MPT,
     temBAD_CIPHERTEXT,
+    temBAD_WASM,
 };
 
 //------------------------------------------------------------------------------
@@ -370,6 +372,7 @@ enum TECcodes : TERUnderlyingType {
     tecNO_DELEGATE_PERMISSION = 198,
     tecBAD_PROOF = 199,
     tecNO_SPONSOR_PERMISSION = 200,
+    tecOUT_OF_GAS = 201,
 };
 
 //------------------------------------------------------------------------------

include/xrpl/protocol/TxFlags.h

@@ -414,40 +414,33 @@ inline constexpr FlagValue tfWithdrawSubTx = tfLPToken | tfSingleAsset | tfTwoAs
 inline constexpr FlagValue tfDepositSubTx =
     tfLPToken | tfSingleAsset | tfTwoAsset | tfOneAssetLPToken | tfLimitLPToken | tfTwoAssetIfEmpty;
 
-// AccountSet SetFlag/ClearFlag values.
-// Format: ASF_FLAG(name, asf_value, lsf_value)
-//   lsf_value is 0 when there is no corresponding ledger-state flag:
-//   - asfAccountTxnID, asfAuthorizedNFTokenMinter: stored as account fields, not flags
-//   - asfAllowTrustLineLocking: has an lsf but is feature-gated (featureTokenEscrow);
-//     callers that need it must handle it separately
-// The JSON key for account_info's account_flags is derived from the name by
-// stripping the "asf" prefix and lowercasing the first character.
-// clang-format off
-#define ACCOUNTSET_FLAGS(ASF_FLAG)                                                         \
-    ASF_FLAG(asfRequireDestinationTag,    1,  lsfRequireDestTag)                           \
-    ASF_FLAG(asfRequireAuthorization,     2,  lsfRequireAuth)                              \
-    ASF_FLAG(asfDisallowIncomingXRP,      3,  lsfDisallowXRP)                              \
-    ASF_FLAG(asfDisableMasterKey,         4,  lsfDisableMaster)                            \
-    ASF_FLAG(asfAccountTxnID,            5,  0) /* no lsf: stored as field */              \
-    ASF_FLAG(asfNoFreeze,                6,  lsfNoFreeze)                                  \
-    ASF_FLAG(asfGlobalFreeze,            7,  lsfGlobalFreeze)                              \
-    ASF_FLAG(asfDefaultRipple,           8,  lsfDefaultRipple)                             \
-    ASF_FLAG(asfDepositAuth,             9,  lsfDepositAuth)                               \
-    ASF_FLAG(asfAuthorizedNFTokenMinter, 10, 0) /* no lsf: stored as field */              \
-    /*  11 is unused */                                                                    \
-    ASF_FLAG(asfDisallowIncomingNFTokenOffer, 12, lsfDisallowIncomingNFTokenOffer)         \
-    ASF_FLAG(asfDisallowIncomingCheck,   13, lsfDisallowIncomingCheck)                     \
-    ASF_FLAG(asfDisallowIncomingPayChan, 14, lsfDisallowIncomingPayChan)                   \
-    ASF_FLAG(asfDisallowIncomingTrustline, 15, lsfDisallowIncomingTrustline)               \
-    ASF_FLAG(asfAllowTrustLineClawback,  16, lsfAllowTrustLineClawback)                    \
-    ASF_FLAG(asfAllowTrustLineLocking,   17, 0) /* feature-gated: featureTokenEscrow */
-// clang-format on
-
+#pragma push_macro("ACCOUNTSET_FLAGS")
 #pragma push_macro("ACCOUNTSET_FLAG_TO_VALUE")
 #pragma push_macro("ACCOUNTSET_FLAG_TO_MAP")
 
-#define ACCOUNTSET_FLAG_TO_VALUE(name, value, lsf) inline constexpr FlagValue name = value;
-#define ACCOUNTSET_FLAG_TO_MAP(name, value, lsf) {#name, value},
+// AccountSet SetFlag/ClearFlag values
+#define ACCOUNTSET_FLAGS(ASF_FLAG)                \
+    ASF_FLAG(asfRequireDest, 1)                   \
+    ASF_FLAG(asfRequireAuth, 2)                   \
+    ASF_FLAG(asfDisallowXRP, 3)                   \
+    ASF_FLAG(asfDisableMaster, 4)                 \
+    ASF_FLAG(asfAccountTxnID, 5)                  \
+    ASF_FLAG(asfNoFreeze, 6)                      \
+    ASF_FLAG(asfGlobalFreeze, 7)                  \
+    ASF_FLAG(asfDefaultRipple, 8)                 \
+    ASF_FLAG(asfDepositAuth, 9)                   \
+    ASF_FLAG(asfAuthorizedNFTokenMinter, 10)      \
+    /*  11 is reserved for Hooks amendment */     \
+    /* ASF_FLAG(asfTshCollect, 11) */             \
+    ASF_FLAG(asfDisallowIncomingNFTokenOffer, 12) \
+    ASF_FLAG(asfDisallowIncomingCheck, 13)        \
+    ASF_FLAG(asfDisallowIncomingPayChan, 14)      \
+    ASF_FLAG(asfDisallowIncomingTrustline, 15)    \
+    ASF_FLAG(asfAllowTrustLineClawback, 16)       \
+    ASF_FLAG(asfAllowTrustLineLocking, 17)
+
+#define ACCOUNTSET_FLAG_TO_VALUE(name, value) inline constexpr FlagValue name = value;
+#define ACCOUNTSET_FLAG_TO_MAP(name, value) {#name, value},
 
 ACCOUNTSET_FLAGS(ACCOUNTSET_FLAG_TO_VALUE)
 
@@ -461,9 +454,11 @@ getAsfFlagMap()
 
 #undef ACCOUNTSET_FLAG_TO_VALUE
 #undef ACCOUNTSET_FLAG_TO_MAP
+#undef ACCOUNTSET_FLAGS
 
 #pragma pop_macro("ACCOUNTSET_FLAG_TO_VALUE")
 #pragma pop_macro("ACCOUNTSET_FLAG_TO_MAP")
+#pragma pop_macro("ACCOUNTSET_FLAGS")
 
 // Sponsor flags (spf)
 

include/xrpl/protocol/jss.h

@@ -110,6 +110,7 @@ JSS(accounts);                    // in: LedgerEntry, Subscribe, handlers/Ledger
 JSS(accounts_proposed);           // in: Subscribe, Unsubscribe
 JSS(action);                      //
 JSS(active);                      // out: OverlayImpl
+JSS(actor);                       // in/out: AccountTx
 JSS(acquiring);                   // out: LedgerRequest
 JSS(address);                     // out: PeerImp
 JSS(affected);                    // out: AcceptedLedgerTx
@@ -133,6 +134,7 @@ JSS(attestation_reward_account);  //
 JSS(auction_slot);                // out: amm_info
 JSS(authorized);                  // out: AccountLines
 JSS(authorize);                   // out: delegate
+JSS(authorizer);                  // in/out: AccountTx
 JSS(authorized_credentials);      // in: ledger_entry DepositPreauth
 JSS(auth_accounts);               // out: amm_info
 JSS(auth_change);                 // out: AccountInfo
@@ -191,6 +193,7 @@ JSS(converge_time);                  // out: NetworkOPs
 JSS(converge_time_s);                // out: NetworkOPs
 JSS(cookie);                         // out: NetworkOPs
 JSS(count);                          // in: AccountTx*, ValidatorList
+JSS(counter_party);                  // in/out: AccountTx
 JSS(counters);                       // in/out: retrieve counters
 JSS(credentials);                    // in: deposit_authorized
 JSS(credential_type);                // in: LedgerEntry DepositPreauth
@@ -270,6 +273,7 @@ JSS(freeze);                         // out: AccountLines
 JSS(freeze_peer);                    // out: AccountLines
 JSS(deep_freeze);                    // out: AccountLines
 JSS(deep_freeze_peer);               // out: AccountLines
+JSS(delegate_filter);                // in/out: AccountTx
 JSS(frozen_balances);                // out: GatewayBalances
 JSS(full);                           // in: LedgerClearer, handlers/Ledger
 JSS(full_reply);                     // out: PathFind

include/xrpl/rdb/RelationalDatabase.h

@@ -46,6 +46,22 @@ struct LedgerRange
     uint32_t max;
 };
 
+/**
+ * @brief Enumeration of possible delegate types that can occur during filtering in account_tx
+ */
+enum class DelegateType {
+    Actor,  ///< Another account signed and submitted transactions on behalf of this account (this
+            ///< account is the owner/delegator).
+    Authorizer  ///< This account signed and submitted transactions on behalf of another account
+                ///< (this account is the signer/delegatee).
+};
+
+struct DelegateFilter
+{
+    DelegateType type = DelegateType::Actor;
+    std::optional<AccountID> counterparty;
+};
+
 class RelationalDatabase
 {
 public:
@@ -82,6 +98,7 @@ public:
         std::optional<AccountTxMarker> marker;
         std::uint32_t limit = 0;
         bool bAdmin = false;
+        std::optional<DelegateFilter> delegate;
     };
 
     using AccountTx = std::pair<std::shared_ptr<Transaction>, std::shared_ptr<TxMeta>>;
@@ -101,6 +118,7 @@ public:
         bool forward = false;
         uint32_t limit = 0;
         std::optional<AccountTxMarker> marker;
+        std::optional<DelegateFilter> delegate;
     };
 
     struct AccountTxResult
@@ -109,6 +127,7 @@ public:
         LedgerRange ledgerRange{};
         uint32_t limit = 0;
         std::optional<AccountTxMarker> marker;
+        std::optional<DelegateFilter> delegate;
     };
 
     virtual ~RelationalDatabase() = default;

include/xrpl/rdb/SociDB.h

@@ -13,7 +13,7 @@
 #include <soci/session.h>
 
 #include <memory>
-#if defined(__clang__)
+#ifdef __clang__
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated"
 #endif
@@ -120,6 +120,6 @@ makeCheckpointer(std::uintptr_t id, std::weak_ptr<soci::session>, JobQueue&, Ser
 
 }  // namespace xrpl
 
-#if defined(__clang__)
+#ifdef __clang__
 #pragma clang diagnostic pop
 #endif

include/xrpl/tx/invariants/InvariantCheck.h

@@ -71,9 +71,18 @@ public:
     /**
      * @brief called for each ledger entry in the current transaction.
      *
-     * @param isDelete true if the SLE is being deleted
-     * @param before ledger entry before modification by the transaction
-     * @param after ledger entry after modification by the transaction
+     * @param isDelete true if the SLE is being deleted.
+     * @param before ledger entry before modification by the transaction. `before` will be null if
+     *  the entry is new.
+     * @param after ledger entry after modification by the transaction. Always non-null. When
+     *  deleting, `after` may differ from `before`. Whether that is important is up to the
+     *  individual invariant check.
+     *
+     * @note `after` IS NEVER NULL. `isDelete` is the only correct way to check for deletions.
+     *  Do not make logic or branching decisions on whether on `after` is set, because it will
+     *  always be set. Treat a null `after` as a programming error (with XRPL_ASSERT). An
+     *  invariant MAY check for null defensively, if it makes more sense, but an assertion is
+     *  preferred for new invariants.
      */
     void
     visitEntry(bool isDelete, SLE::const_ref before, SLE::const_ref after);
@@ -316,17 +325,26 @@ public:
 };
 
 /**
- * @brief Invariant: Token holder's trustline balance cannot be negative after
- * Clawback.
+ * @brief Invariant: Token holder's trustline/MPT balance cannot be invalid
+ * after Clawback.
  *
  * We iterate all the trust lines affected by this transaction and ensure
  * that no more than one trustline is modified, and also holder's balance is
- * non-negative.
+ * non-negative. When featureMPTokensV2 is enabled, also verify the holder's
+ * raw trustline/MPToken balance decreased by the clawed amount.
  */
 class ValidClawback
 {
+    struct EntryChange
+    {
+        SLE::const_pointer before;
+        SLE::const_pointer after;
+    };
+
     std::uint32_t trustlinesChanged_ = 0;
     std::uint32_t mptokensChanged_ = 0;
+    EntryChange iou_;
+    EntryChange mpt_;
 
 public:
     void
@@ -440,7 +458,7 @@ using InvariantChecks = std::tuple<
     ValidLoan,
     ValidVault,
     ValidConfidentialMPToken,
-    ValidMPTPayment,
+    ValidMPTBalanceChanges,
     ValidAmounts,
     ValidMPTTransfer,
     ObjectHasPseudoAccount,

include/xrpl/tx/invariants/MPTInvariant.h

@@ -87,7 +87,7 @@ public:
  * OutstandingAmount after application equals OutstandingAmount before
  * application plus the net holder balance delta.
  */
-class ValidMPTPayment
+class ValidMPTBalanceChanges
 {
     enum class Order { Before = 0, After = 1 };
     struct MPTData

include/xrpl/tx/transactors/system/Batch.h

@@ -12,6 +12,7 @@
 
 #include <array>
 #include <cstdint>
+#include <optional>
 
 namespace xrpl {
 
@@ -39,6 +40,9 @@ public:
     static NotTEC
     checkSign(PreclaimContext const& ctx);
 
+    static TER
+    preclaim(PreclaimContext const& ctx);
+
     TER
     doApply() override;
 
@@ -76,6 +80,10 @@ private:
     // only be reached through Batch::checkSign.
     static NotTEC
     checkBatchSign(PreclaimContext const& ctx);
+
+    // nullopt on overflow or oversized signer arrays.
+    static std::optional<XRPAmount>
+    calculateBaseFeeImpl(ReadView const& view, STTx const& tx);
 };
 
 }  // namespace xrpl

include/xrpl/tx/wasm/HostFunc.h

@@ -0,0 +1,523 @@
+#pragma once
+
+#include <xrpl/basics/Slice.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/contract.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Asset.h>
+#include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/UintTypes.h>
+#include <xrpl/tx/wasm/WasmCommon.h>
+
+#include <cstdint>
+#include <expected>
+#include <functional>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+
+namespace xrpl {
+
+namespace wasm_float {
+
+std::string
+floatToString(Slice const& data);
+
+std::expected<Bytes, HostFunctionError>
+floatFromIntImpl(int64_t x, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatFromUintImpl(uint64_t x, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatFromSTAmountImpl(STAmount const& x, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatFromSTNumberImpl(STNumber const& x, int32_t mode);
+
+std::expected<int64_t, HostFunctionError>
+floatToIntImpl(Slice const& x, int32_t mode);
+
+std::expected<FloatPair, HostFunctionError>
+floatToMantExpImpl(Slice const& x);
+
+std::expected<Bytes, HostFunctionError>
+floatFromMantExpImpl(int64_t mantissa, int32_t exponent, int32_t mode);
+
+std::expected<int32_t, HostFunctionError>
+floatCompareImpl(Slice const& x, Slice const& y);
+
+std::expected<Bytes, HostFunctionError>
+floatAddImpl(Slice const& x, Slice const& y, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatSubtractImpl(Slice const& x, Slice const& y, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatMultiplyImpl(Slice const& x, Slice const& y, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatDivideImpl(Slice const& x, Slice const& y, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatRootImpl(Slice const& x, int32_t n, int32_t mode);
+
+std::expected<Bytes, HostFunctionError>
+floatPowerImpl(Slice const& x, int32_t n, int32_t mode);
+
+}  // namespace wasm_float
+
+// Intended to work only through wasm runtime. Don't call them directly, except with unit tests
+class HostFunctions
+{
+protected:
+    RTOptRef rt_;
+    beast::Journal j_;
+
+public:
+    HostFunctions(beast::Journal j = beast::Journal{beast::Journal::getNullSink()}) : j_(j)
+    {
+    }
+
+    void
+    setRT(WasmRuntimeWrapper& rt)
+    {
+        rt_ = rt;
+    }
+
+    void
+    resetRT()
+    {
+        rt_ = std::nullopt;
+    }
+
+    [[nodiscard]] WasmRuntimeWrapper&
+    getRT() const
+    {
+        if (!rt_)
+            Throw<std::logic_error>("Wasm runtime not set");
+        return rt_->get();
+    }
+
+    [[nodiscard]] beast::Journal
+    getJournal() const
+    {
+        return j_;
+    }
+
+    // LCOV_EXCL_START
+
+    [[nodiscard]] virtual bool
+    checkSelf() const
+    {
+        return true;
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<std::uint32_t, HostFunctionError>
+    getLedgerSqn() const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<std::uint32_t, HostFunctionError>
+    getParentLedgerTime() const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Hash, HostFunctionError>
+    getParentLedgerHash() const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<uint32_t, HostFunctionError>
+    getBaseFee() const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    isAmendmentEnabled(uint256 const& amendmentId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    isAmendmentEnabled(std::string_view const& amendmentName) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    virtual std::expected<int32_t, HostFunctionError>
+    cacheLedgerObj(uint256 const& objId, int32_t cacheIdx)
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getTxField(SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getCurrentLedgerObjField(SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getLedgerObjField(int32_t cacheIdx, SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getTxNestedField(FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getCurrentLedgerObjNestedField(FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getLedgerObjNestedField(int32_t cacheIdx, FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getTxArrayLen(SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getCurrentLedgerObjArrayLen(SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getLedgerObjArrayLen(int32_t cacheIdx, SField const& fname) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getTxNestedArrayLen(FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getCurrentLedgerObjNestedArrayLen(FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getLedgerObjNestedArrayLen(int32_t cacheIdx, FieldLocator const& locator) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    virtual std::expected<int32_t, HostFunctionError>
+    updateData(Slice const& data)
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    checkSignature(Slice const& message, Slice const& signature, Slice const& pubkey) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Hash, HostFunctionError>
+    computeSha512HalfHash(Slice const& data) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    accountKeylet(AccountID const& account) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    ammKeylet(Asset const& issue1, Asset const& issue2) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    checkKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    credentialKeylet(AccountID const& subject, AccountID const& issuer, Slice const& credentialType)
+        const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    didKeylet(AccountID const& account) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    delegateKeylet(AccountID const& account, AccountID const& authorize) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    depositPreauthKeylet(AccountID const& account, AccountID const& authorize) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    escrowKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    trustLineKeylet(AccountID const& account1, AccountID const& account2, Currency const& currency)
+        const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    mptokenIssuanceKeylet(AccountID const& issuer, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    mptokenKeylet(MPTID const& mptid, AccountID const& holder) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    nftokenOfferKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    offerKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    oracleKeylet(AccountID const& account, std::uint32_t docId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    paychannelKeylet(AccountID const& account, AccountID const& destination, std::uint32_t seq)
+        const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    permissionedDomainKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    signerListKeylet(AccountID const& account) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    ticketKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    vaultKeylet(AccountID const& account, std::uint32_t seq) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getNFT(AccountID const& account, uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    getNFTIssuer(uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<std::uint32_t, HostFunctionError>
+    getNFTTaxon(uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getNFTFlags(uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    getNFTTransferFee(uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<std::uint32_t, HostFunctionError>
+    getNFTSequence(uint256 const& nftId) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    trace(std::string_view const& msg, Slice const& data, bool asHex) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    traceNum(std::string_view const& msg, int64_t data) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    traceAccount(std::string_view const& msg, AccountID const& account) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    traceFloat(std::string_view const& msg, Slice const& data) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    traceAmount(std::string_view const& msg, STAmount const& amount) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatFromInt(int64_t x, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatFromUint(uint64_t x, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatFromSTAmount(STAmount const& x, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatFromSTNumber(STNumber const& x, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int64_t, HostFunctionError>
+    floatToInt(Slice const& x, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<FloatPair, HostFunctionError>
+    floatToMantExp(Slice const& x) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatFromMantExp(int64_t mantissa, int32_t exponent, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<int32_t, HostFunctionError>
+    floatCompare(Slice const& x, Slice const& y) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatAdd(Slice const& x, Slice const& y, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatSubtract(Slice const& x, Slice const& y, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatMultiply(Slice const& x, Slice const& y, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatDivide(Slice const& x, Slice const& y, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatRoot(Slice const& x, int32_t n, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    [[nodiscard]] [[nodiscard]] virtual std::expected<Bytes, HostFunctionError>
+    floatPower(Slice const& x, int32_t n, int32_t mode) const
+    {
+        return std::unexpected(HostFunctionError::Unimplemented);
+    }
+
+    virtual ~HostFunctions() = default;
+    // LCOV_EXCL_STOP
+};
+
+using HFRef = std::reference_wrapper<HostFunctions>;
+
+}  // namespace xrpl

include/xrpl/tx/wasm/HostFuncImpl.h

@@ -0,0 +1,302 @@
+#pragma once
+
+#include <xrpl/basics/Slice.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/core/ServiceRegistry.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Asset.h>
+#include <xrpl/protocol/Keylet.h>
+#include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/STAmount.h>
+#include <xrpl/protocol/UintTypes.h>
+#include <xrpl/tx/ApplyContext.h>
+#include <xrpl/tx/wasm/HostFunc.h>
+#include <xrpl/tx/wasm/WasmCommon.h>
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <expected>
+#include <memory>
+#include <optional>
+#include <string_view>
+
+namespace xrpl {
+
+// Intended to work only through wasm runtime. Don't call them directly, except with unit tests
+class WasmHostFunctionsImpl : public HostFunctions
+{
+    ApplyContext& ctx_;
+
+    Keylet leKey_;
+    mutable std::optional<std::shared_ptr<SLE const>> currentLedgerObj_;
+
+    static int constexpr maxCache = 256;
+    std::array<std::shared_ptr<SLE const>, maxCache> cache_;
+
+    std::optional<Bytes> data_;
+
+public:
+    std::expected<std::shared_ptr<SLE const>, HostFunctionError>
+    getCurrentLedgerObj() const
+    {
+        if (!currentLedgerObj_)
+            currentLedgerObj_ = ctx_.view().read(leKey_);
+        if (*currentLedgerObj_)
+            return *currentLedgerObj_;
+        return std::unexpected(HostFunctionError::LedgerObjNotFound);
+    }
+
+    std::expected<int32_t, HostFunctionError>
+    normalizeCacheIndex(int32_t cacheIdx) const
+    {
+        --cacheIdx;
+        if (cacheIdx < 0 || cacheIdx >= maxCache)
+            return std::unexpected(HostFunctionError::SlotOutRange);
+        if (!cache_[cacheIdx])
+            return std::unexpected(HostFunctionError::EmptySlot);
+        return cacheIdx;
+    }
+
+    template <typename F>
+    void
+    log(std::string_view const& msg, F&& dataFn) const
+    {
+#ifdef DEBUG_OUTPUT
+        auto& j = std::cerr;
+#else
+        if (!getJournal().active(beast::Severity::Trace))
+            return;
+        auto j = getJournal().trace();
+#endif
+        j << "WasmTrace[" << toShortString(leKey_.key) << "]: " << msg << " " << dataFn();
+
+#ifdef DEBUG_OUTPUT
+        j << std::endl;
+#endif
+    }
+
+public:
+    WasmHostFunctionsImpl(ApplyContext& ct, Keylet const& leKey)
+        : HostFunctions(ct.journal), ctx_(ct), leKey_(leKey)
+    {
+    }
+
+    bool
+    checkSelf() const override
+    {
+        return !currentLedgerObj_ && !data_ &&
+            std::ranges::none_of(cache_, [](auto const& p) { return !!p; });
+    }
+
+    std::optional<Bytes> const&
+    getData() const
+    {
+        return data_;
+    }
+
+    std::expected<std::uint32_t, HostFunctionError>
+    getLedgerSqn() const override;
+
+    std::expected<std::uint32_t, HostFunctionError>
+    getParentLedgerTime() const override;
+
+    std::expected<Hash, HostFunctionError>
+    getParentLedgerHash() const override;
+
+    std::expected<std::uint32_t, HostFunctionError>
+    getBaseFee() const override;
+
+    std::expected<int32_t, HostFunctionError>
+    isAmendmentEnabled(uint256 const& amendmentId) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    isAmendmentEnabled(std::string_view const& amendmentName) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    cacheLedgerObj(uint256 const& objId, int32_t cacheIdx) override;
+
+    std::expected<Bytes, HostFunctionError>
+    getTxField(SField const& fname) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getCurrentLedgerObjField(SField const& fname) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getLedgerObjField(int32_t cacheIdx, SField const& fname) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getTxNestedField(FieldLocator const& locator) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getCurrentLedgerObjNestedField(FieldLocator const& locator) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getLedgerObjNestedField(int32_t cacheIdx, FieldLocator const& locator) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getTxArrayLen(SField const& fname) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getCurrentLedgerObjArrayLen(SField const& fname) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getLedgerObjArrayLen(int32_t cacheIdx, SField const& fname) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getTxNestedArrayLen(FieldLocator const& locator) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getCurrentLedgerObjNestedArrayLen(FieldLocator const& locator) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getLedgerObjNestedArrayLen(int32_t cacheIdx, FieldLocator const& locator) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    updateData(Slice const& data) override;
+
+    std::expected<int32_t, HostFunctionError>
+    checkSignature(Slice const& message, Slice const& signature, Slice const& pubkey)
+        const override;
+
+    std::expected<Hash, HostFunctionError>
+    computeSha512HalfHash(Slice const& data) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    accountKeylet(AccountID const& account) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    ammKeylet(Asset const& issue1, Asset const& issue2) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    checkKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    credentialKeylet(AccountID const& subject, AccountID const& issuer, Slice const& credentialType)
+        const override;
+
+    std::expected<Bytes, HostFunctionError>
+    didKeylet(AccountID const& account) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    delegateKeylet(AccountID const& account, AccountID const& authorize) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    depositPreauthKeylet(AccountID const& account, AccountID const& authorize) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    escrowKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    trustLineKeylet(AccountID const& account1, AccountID const& account2, Currency const& currency)
+        const override;
+
+    std::expected<Bytes, HostFunctionError>
+    mptokenIssuanceKeylet(AccountID const& issuer, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    mptokenKeylet(MPTID const& mptid, AccountID const& holder) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    nftokenOfferKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    offerKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    oracleKeylet(AccountID const& account, std::uint32_t docId) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    paychannelKeylet(AccountID const& account, AccountID const& destination, std::uint32_t seq)
+        const override;
+
+    std::expected<Bytes, HostFunctionError>
+    permissionedDomainKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    signerListKeylet(AccountID const& account) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    ticketKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    vaultKeylet(AccountID const& account, std::uint32_t seq) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getNFT(AccountID const& account, uint256 const& nftId) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    getNFTIssuer(uint256 const& nftId) const override;
+
+    std::expected<std::uint32_t, HostFunctionError>
+    getNFTTaxon(uint256 const& nftId) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getNFTFlags(uint256 const& nftId) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    getNFTTransferFee(uint256 const& nftId) const override;
+
+    std::expected<std::uint32_t, HostFunctionError>
+    getNFTSequence(uint256 const& nftId) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    trace(std::string_view const& msg, Slice const& data, bool asHex) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    traceNum(std::string_view const& msg, int64_t data) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    traceAccount(std::string_view const& msg, AccountID const& account) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    traceFloat(std::string_view const& msg, Slice const& data) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    traceAmount(std::string_view const& msg, STAmount const& amount) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatFromInt(int64_t x, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatFromUint(uint64_t x, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatFromSTAmount(STAmount const& x, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatFromSTNumber(STNumber const& x, int32_t mode) const override;
+
+    std::expected<int64_t, HostFunctionError>
+    floatToInt(Slice const& x, int32_t mode) const override;
+
+    std::expected<FloatPair, HostFunctionError>
+    floatToMantExp(Slice const& x) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatFromMantExp(int64_t mantissa, int32_t exponent, int32_t mode) const override;
+
+    std::expected<int32_t, HostFunctionError>
+    floatCompare(Slice const& x, Slice const& y) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatAdd(Slice const& x, Slice const& y, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatSubtract(Slice const& x, Slice const& y, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatMultiply(Slice const& x, Slice const& y, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatDivide(Slice const& x, Slice const& y, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatRoot(Slice const& x, int32_t n, int32_t mode) const override;
+
+    std::expected<Bytes, HostFunctionError>
+    floatPower(Slice const& x, int32_t n, int32_t mode) const override;
+};
+
+}  // namespace xrpl

include/xrpl/tx/wasm/HostFuncWrapper.h

@@ -0,0 +1,254 @@
+#pragma once
+
+#include <xrpl/tx/wasm/HostFunc.h>
+
+#include <wasm.h>
+
+#include <cstdint>
+
+namespace xrpl {
+
+#define WASM_CB_PARAMS_LIST void *env, wasm_val_vec_t const *params, wasm_val_vec_t *results
+#define WASM_SECONDARY_CB_PARAMS_LIST \
+    HostFunctions &hf, wasm_val_vec_t const *params, wasm_val_vec_t *results
+
+wasm_trap_t* HostFuncMain_wrap(WASM_CB_PARAMS_LIST);
+
+using getLedgerSqn_proto = int32_t(uint8_t*, int32_t);
+wasm_trap_t* getLedgerSqn_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getParentLedgerTime_proto = int32_t(uint8_t*, int32_t);
+wasm_trap_t* getParentLedgerTime_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getParentLedgerHash_proto = int32_t(uint8_t*, int32_t);
+wasm_trap_t* getParentLedgerHash_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getBaseFee_proto = int32_t(uint8_t*, int32_t);
+wasm_trap_t* getBaseFee_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using isAmendmentEnabled_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* isAmendmentEnabled_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using cacheLedgerObj_proto = int32_t(uint8_t const*, int32_t, int32_t);
+wasm_trap_t* cacheLedgerObj_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getTxField_proto = int32_t(int32_t, uint8_t*, int32_t);
+wasm_trap_t* getTxField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getCurrentLedgerObjField_proto = int32_t(int32_t, uint8_t*, int32_t);
+wasm_trap_t* getCurrentLedgerObjField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getLedgerObjField_proto = int32_t(int32_t, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getLedgerObjField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getTxNestedField_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getTxNestedField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getCurrentLedgerObjNestedField_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getCurrentLedgerObjNestedField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getLedgerObjNestedField_proto = int32_t(int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getLedgerObjNestedField_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getTxArrayLen_proto = int32_t(int32_t);
+wasm_trap_t* getTxArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getCurrentLedgerObjArrayLen_proto = int32_t(int32_t);
+wasm_trap_t* getCurrentLedgerObjArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getLedgerObjArrayLen_proto = int32_t(int32_t, int32_t);
+wasm_trap_t* getLedgerObjArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getTxNestedArrayLen_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* getTxNestedArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getCurrentLedgerObjNestedArrayLen_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* getCurrentLedgerObjNestedArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getLedgerObjNestedArrayLen_proto = int32_t(int32_t, uint8_t const*, int32_t);
+wasm_trap_t* getLedgerObjNestedArrayLen_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using updateData_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* updateData_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using checkSignature_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t const*, int32_t);
+wasm_trap_t* checkSignature_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using computeSha512HalfHash_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* computeSha512HalfHash_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using accountKeylet_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* accountKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using ammKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* ammKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using checkKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* checkKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using credentialKeylet_proto = int32_t(
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t*,
+    int32_t);
+wasm_trap_t* credentialKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using delegateKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* delegateKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using depositPreauthKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* depositPreauthKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using didKeylet_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* didKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using escrowKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* escrowKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using trustLineKeylet_proto = int32_t(
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t*,
+    int32_t);
+wasm_trap_t* trustLineKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using mptokenIssuanceKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* mptokenIssuanceKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using mptokenKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* mptokenKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using nftokenOfferKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* nftokenOfferKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using offerKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* offerKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using oracleKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* oracleKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using paychannelKeylet_proto = int32_t(
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t const*,
+    int32_t,
+    uint8_t*,
+    int32_t);
+wasm_trap_t* paychannelKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using permissionedDomainKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* permissionedDomainKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using signerListKeylet_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* signerListKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using ticketKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* ticketKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using vaultKeylet_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* vaultKeylet_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFT_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getNFT_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFTIssuer_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getNFTIssuer_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFTTaxon_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getNFTTaxon_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFTFlags_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* getNFTFlags_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFTTransferFee_proto = int32_t(uint8_t const*, int32_t);
+wasm_trap_t* getNFTTransferFee_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using getNFTSequence_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* getNFTSequence_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using trace_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, int32_t);
+wasm_trap_t* trace_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using traceNum_proto = int32_t(uint8_t const*, int32_t, int64_t);
+wasm_trap_t* traceNum_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using traceAccount_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t);
+wasm_trap_t* traceAccount_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using traceFloat_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t);
+wasm_trap_t* traceFloat_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using traceAmount_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t);
+wasm_trap_t* traceAmount_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatFromInt_proto = int32_t(int64_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatFromInt_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatFromUint_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatFromUint_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatFromSTAmount_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatFromSTAmount_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatFromSTNumber_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatFromSTNumber_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatToInt_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatToInt_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatToMantExp_proto = int32_t(uint8_t const*, int32_t, uint8_t*, int32_t, uint8_t*, int32_t);
+wasm_trap_t* floatToMantExp_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatFromMantExp_proto = int32_t(int64_t, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatFromMantExp_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatCompare_proto = int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t);
+wasm_trap_t* floatCompare_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatAdd_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatAdd_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatSubtract_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatSubtract_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatMultiply_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatMultiply_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatDivide_proto =
+    int32_t(uint8_t const*, int32_t, uint8_t const*, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatDivide_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatRoot_proto = int32_t(uint8_t const*, int32_t, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatRoot_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+using floatPower_proto = int32_t(uint8_t const*, int32_t, int32_t, uint8_t*, int32_t, int32_t);
+wasm_trap_t* floatPower_wrap(WASM_SECONDARY_CB_PARAMS_LIST);
+
+}  // namespace xrpl

include/xrpl/tx/wasm/README.md

@@ -0,0 +1,189 @@
+# WASM Module for Programmable Escrows
+
+This module provides WebAssembly (WASM) execution capabilities for programmable
+escrows on the XRP Ledger. When an escrow is finished, the WASM code runs to
+determine whether the escrow conditions are met, enabling custom programmable
+logic for escrow release conditions.
+
+For the full specification, see
+[XLS-0102: WASM VM](https://xls.xrpl.org/xls/XLS-0102-wasm-vm.html).
+
+## Architecture
+
+The module follows a layered architecture:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                 WasmEngine (WasmVM.h)                       │
+│         runEscrowWasm(), preflightEscrowWasm()              │
+│              Host function registration                     │
+├─────────────────────────────────────────────────────────────┤
+│                 WasmiEngine (WasmiVM.h)                     │
+│            Low-level wasmi interpreter integration          │
+├─────────────────────────────────────────────────────────────┤
+│    HostFuncWrapper          │       HostFuncImpl            │
+│   C-style WASM bridges      │   C++ implementations         │
+├─────────────────────────────────────────────────────────────┤
+│                   HostFunc (Interface)                      │
+│            Abstract base class for host functions           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+- **`WasmVM.h` / `detail/WasmVM.cpp`** - High-level facade providing:
+  - `WasmEngine` singleton that wraps the underlying WASM interpreter
+  - `runEscrowWasm()` - Execute WASM code for escrow finish
+  - `preflightEscrowWasm()` - Validate WASM code during preflight
+  - `createWasmImport()` - Register all host functions
+
+- **`WasmiVM.h` / `detail/WasmiVM.cpp`** - Low-level integration with the
+  [wasmi](https://github.com/wasmi-labs/wasmi) WebAssembly interpreter:
+  - `WasmiEngine` - Manages WASM modules, instances, and execution
+  - Memory management and gas metering
+  - Function invocation and result handling
+
+- **`HostFunc.h`** - Abstract `HostFunctions` base class defining the interface
+  for all callable host functions. Each method returns
+  `std::expected<T, HostFunctionError>`.
+
+- **`HostFuncImpl.h` / `detail/HostFuncImpl*.cpp`** - Concrete
+  `WasmHostFunctionsImpl` class that implements host functions with access to
+  `ApplyContext` for ledger state queries. Implementation split across files:
+  - `HostFuncImpl.cpp` - Core utilities (updateData, checkSignature, etc.)
+  - `HostFuncImplFloat.cpp` - Float/number arithmetic operations
+  - `HostFuncImplGetter.cpp` - Field access (transaction, ledger objects)
+  - `HostFuncImplKeylet.cpp` - Keylet construction functions
+  - `HostFuncImplLedgerHeader.cpp` - Ledger header info access
+  - `HostFuncImplNFT.cpp` - NFT-related queries
+  - `HostFuncImplTrace.cpp` - Debugging/tracing functions
+
+- **`HostFuncWrapper.h` / `detail/HostFuncWrapper.cpp`** - C-style wrapper
+  functions that bridge WASM calls to C++ `HostFunctions` methods. Each host
+  function has:
+  - A `_proto` type alias defining the function signature
+  - A `_wrap` function that extracts parameters and calls the implementation
+
+- **`ParamsHelper.h`** - Utilities for WASM parameter handling:
+  - `WASM_IMPORT_FUNC` / `WASM_IMPORT_FUNC2` macros for registration
+  - `wasmParams()` helper for building parameter vectors
+  - Type conversion between WASM and C++ types
+
+## Host Functions
+
+Host functions allow WASM code to interact with the XRP Ledger. They are
+organized into categories:
+
+- **Ledger Information** - Access ledger sequence, timestamps, hashes, fees
+- **Transaction & Ledger Object Access** - Read fields from the transaction
+  and ledger objects (including the current escrow object)
+- **Keylet Construction** - Build keylets to look up various ledger object types
+- **Cryptography** - Signature verification and hashing
+- **Float Arithmetic** - Mathematical operations for amount calculations
+- **NFT Operations** - Query NFT properties
+- **Tracing/Debugging** - Log messages for debugging
+
+For the complete list of available host functions, their WASM names, and gas
+costs, see the [XLS-0102 specification](https://xls.xrpl.org/xls/XLS-0102-wasm-vm.html)
+or `detail/WasmVM.cpp` where they are registered via `WASM_IMPORT_FUNC2` macros.
+For method signatures, see `HostFunc.h`.
+
+## Gas Model
+
+Each host function has an associated gas cost. The gas cost is specified when
+registering the function in `detail/WasmVM.cpp`:
+
+```cpp
+WASM_IMPORT_FUNC2(i, getLedgerSqn, "get_ledger_sqn", hfs, 60);
+//                                                        ^^ gas cost
+```
+
+WASM execution is metered, and if the gas limit is exceeded, execution fails.
+
+## Entry Point
+
+The WASM module must export a function with the name defined by
+`escrowFunctionName` (currently `"escrow_finish"`). This function:
+
+- Takes no parameters (or parameters passed via host function calls)
+- Returns an `int32_t`:
+  - `1` (or positive): Escrow conditions are met, allow finish
+  - `0` (or negative): Escrow conditions are not met, reject finish
+
+## Adding a New Host Function
+
+To add a new host function, follow these steps:
+
+### 1. Add to HostFunc.h (Base Class)
+
+Add a virtual method declaration with a default implementation that returns an
+error:
+
+```cpp
+virtual std::expected<ReturnType, HostFunctionError>
+myNewFunction(ParamType1 param1, ParamType2 param2)
+{
+    return std::unexpected(HostFunctionError::INTERNAL);
+}
+```
+
+### 2. Add to HostFuncImpl.h (Declaration)
+
+Add the method override declaration in `WasmHostFunctionsImpl`:
+
+```cpp
+std::expected<ReturnType, HostFunctionError>
+myNewFunction(ParamType1 param1, ParamType2 param2) override;
+```
+
+### 3. Implement in detail/HostFuncImpl\*.cpp
+
+Add the implementation in the appropriate file:
+
+```cpp
+std::expected<ReturnType, HostFunctionError>
+WasmHostFunctionsImpl::myNewFunction(ParamType1 param1, ParamType2 param2)
+{
+    // Implementation using ctx (ApplyContext) for ledger access
+    return result;
+}
+```
+
+### 4. Add Wrapper to HostFuncWrapper.h
+
+Add the prototype and wrapper declaration:
+
+```cpp
+using myNewFunction_proto = int32_t(uint8_t const*, int32_t, ...);
+wasm_trap_t*
+myNewFunction_wrap(void* env, wasm_val_vec_t const* params, wasm_val_vec_t* results);
+```
+
+### 5. Implement Wrapper in detail/HostFuncWrapper.cpp
+
+Implement the C-style wrapper that bridges WASM to C++:
+
+```cpp
+wasm_trap_t*
+myNewFunction_wrap(void* env, wasm_val_vec_t const* params, wasm_val_vec_t* results)
+{
+    // Extract parameters from params
+    // Call hfs->myNewFunction(...)
+    // Set results and return
+}
+```
+
+### 6. Register in WasmVM.cpp
+
+Add the function registration in `setCommonHostFunctions()` or
+`createWasmImport()`:
+
+```cpp
+WASM_IMPORT_FUNC2(i, myNewFunction, "my_new_function", hfs, 100);
+//                                   ^^ WASM name       ^^ gas cost
+```
+
+> [!IMPORTANT]
+> New host functions MUST be amendment-gated in `WasmVM.cpp`.
+> Wrap the registration in an amendment check to ensure the function is only
+> available after the corresponding amendment is enabled on the network.

include/xrpl/tx/wasm/WasmCommon.h

@@ -0,0 +1,241 @@
+#pragma once
+
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/contract.h>
+#include <xrpl/protocol/TER.h>
+
+#include <bit>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <stdexcept>
+#include <string_view>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace xrpl {
+
+using Bytes = std::vector<std::uint8_t>;
+using Hash = xrpl::uint256;
+using FloatPair = std::pair<int64_t, int32_t>;
+
+// Error signals that cross the wasm boundary as trap messages (the C API has no
+// trap code). WasmiEngine::call maps them to TER: hfErrInternal -> tecINTERNAL,
+// hfErrOutOfGas / wasmi's OutOfFuel -> tecOUT_OF_GAS, anything else ->
+// tecFAILED_PROCESSING.
+//
+// Matched as substrings, not by equality: the C API returns the Rust Debug form
+// of the error, e.g. `Error { kind: Message("HfInternal") }` or
+// `Error { kind: TrapCode(OutOfFuel) }`.
+std::string_view inline constexpr hfErrInternal = "HfInternal";
+std::string_view inline constexpr hfErrOutOfGas = "HfOutOfGas";
+std::string_view inline constexpr wasmiTrapOutOfFuel = "OutOfFuel";
+
+enum class HostFunctionError : int32_t {
+    Unimplemented = -1,
+    FieldNotFound = -2,
+    BufferTooSmall = -3,
+    NoArray = -4,
+    NotLeafField = -5,
+    LocatorMalformed = -6,
+    SlotOutRange = -7,
+    SlotsFull = -8,
+    EmptySlot = -9,
+    LedgerObjNotFound = -10,
+    OutOfTransferLimit = -11,
+    DataFieldTooLarge = -12,
+    PointerOutOfBounds = -13,
+    NoMemExported = -14,
+    InvalidParams = -15,
+    InvalidAccount = -16,
+    InvalidField = -17,
+    IndexOutOfBounds = -18,
+    FloatInputMalformed = -19,
+    FloatComputationError = -20,
+};
+
+enum class WasmTypes { WtI32, WtI64 };
+
+struct Wmem
+{
+    std::uint8_t* p = nullptr;
+    std::size_t s = 0;
+
+    Wmem() = default;
+    Wmem(void* ptr, std::size_t size) : p(reinterpret_cast<std::uint8_t*>(ptr)), s(size)
+    {
+    }
+};
+
+template <typename T>
+struct WasmResult
+{
+    T result;
+    int64_t cost;
+};
+using EscrowResult = WasmResult<int32_t>;
+
+// Engine error when wasm does not run to completion. `cost` is the gas consumed
+// when meaningful (tecOUT_OF_GAS / tecFAILED_PROCESSING; caller writes it to tx
+// metadata); std::nullopt for tecINTERNAL and malformed input (no gas reported).
+struct WasmTER
+{
+    TER ter;
+    std::optional<int64_t> cost;
+};
+
+class FieldLocator
+{
+    int32_t const* ptr_ = nullptr;
+    uint32_t size_ = 0;
+    std::vector<int32_t> buf_;
+
+public:
+    FieldLocator(std::vector<int32_t>&& buf)
+        : ptr_(&buf[0]), size_(buf.size()), buf_(std::move(buf))
+    {
+    }
+
+    FieldLocator(int32_t const* ptr, uint32_t const size) : ptr_(ptr), size_(size)
+    {
+    }
+
+    FieldLocator(FieldLocator const&) = delete;
+    FieldLocator&
+    operator=(FieldLocator const&) = delete;
+    FieldLocator(FieldLocator&&) = default;
+    FieldLocator&
+    operator=(FieldLocator&&) = default;
+
+    int32_t
+    operator[](unsigned i) const
+    {
+        if (i >= size_)
+            Throw<std::runtime_error>("index out of bounds");
+        return ptr_[i];
+    }
+
+    [[nodiscard]] uint32_t
+    size() const
+    {
+        return size_;
+    }
+
+    [[nodiscard]] int32_t const*
+    data() const
+    {
+        return ptr_;
+    }
+
+    [[nodiscard]] bool
+    empty() const
+    {
+        return size_ == 0;
+    }
+};
+
+class WasmRuntimeWrapper
+{
+public:
+    virtual ~WasmRuntimeWrapper() = default;
+
+    virtual Wmem
+    getMem() = 0;
+
+    virtual std::int64_t
+    getGas() = 0;
+
+    virtual std::int64_t
+    setGas(std::int64_t gas) = 0;
+
+    virtual std::int64_t
+    getTransferLimit() = 0;
+
+    virtual std::int64_t
+    setTransferLimit(std::int64_t transferLimit) = 0;
+};
+using RTOptRef = std::optional<std::reference_wrapper<WasmRuntimeWrapper>>;
+
+struct WasmParam
+{
+    // We are not supporting float/double
+
+    WasmTypes type = WasmTypes::WtI32;
+    union
+    {
+        std::int32_t i32;
+        std::int64_t i64 = 0;
+    } of;
+};
+
+template <class... Types>
+inline void
+wasmParamsHlp(std::vector<WasmParam>& v, std::int32_t p, Types&&... args)
+{
+    v.push_back({.type = WasmTypes::WtI32, .of = {.i32 = p}});
+    wasmParamsHlp(v, std::forward<Types>(args)...);
+}
+
+template <class... Types>
+inline void
+wasmParamsHlp(std::vector<WasmParam>& v, std::int64_t p, Types&&... args)
+{
+    v.push_back({.type = WasmTypes::WtI64, .of = {.i64 = p}});
+    wasmParamsHlp(v, std::forward<Types>(args)...);
+}
+
+inline void
+wasmParamsHlp(std::vector<WasmParam>& v)
+{
+}
+
+template <class... Types>
+inline std::vector<WasmParam>
+wasmParams(Types&&... args)
+{
+    std::vector<WasmParam> v;
+    v.reserve(sizeof...(args));
+    wasmParamsHlp(v, std::forward<Types>(args)...);
+    return v;
+}
+
+template <typename T, size_t Size = sizeof(T)>
+constexpr T
+adjustWasmEndianessHlp(T x)
+{
+    static_assert(std::is_integral_v<T>, "Only integral types");
+    if constexpr (Size > 1)
+    {
+        using U = std::make_unsigned_t<T>;
+        U u = static_cast<U>(x);
+        U const low = (u & 0xFF) << ((Size - 1) << 3);
+        u = adjustWasmEndianessHlp<U, Size - 1>(u >> 8);
+        return static_cast<T>(low | u);
+    }
+
+    return x;
+}
+
+template <typename T, size_t Size = sizeof(T)>
+constexpr T
+adjustWasmEndianess(T x)
+{
+    // LCOV_EXCL_START
+    static_assert(std::is_integral_v<T>, "Only integral types");
+    if constexpr (std::endian::native == std::endian::big)
+    {
+        return adjustWasmEndianessHlp(x);
+    }
+    return x;
+    // LCOV_EXCL_STOP
+}
+
+constexpr int32_t
+hfErrorToInt(HostFunctionError e)
+{
+    return static_cast<int32_t>(e);
+}
+
+}  // namespace xrpl

include/xrpl/tx/wasm/WasmImportsHelper.h

@@ -0,0 +1,126 @@
+#pragma once
+
+#include <xrpl/tx/wasm/HostFunc.h>
+#include <xrpl/tx/wasm/WasmCommon.h>
+
+#include <boost/function_types/function_arity.hpp>
+#include <boost/function_types/parameter_types.hpp>
+#include <boost/function_types/result_type.hpp>
+#include <boost/mpl/vector.hpp>
+
+#include <wasm.h>
+
+#include <cstdint>
+#include <optional>
+#include <string_view>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace bft = boost::function_types;
+
+namespace xrpl {
+
+using wasmSecondaryCbFuncType =
+    wasm_trap_t*(HostFunctions&, wasm_val_vec_t const*, wasm_val_vec_t*);
+
+struct WasmImportFunc
+{
+    std::string_view name;
+    std::optional<WasmTypes> result;
+    std::vector<WasmTypes> params;
+
+    wasmSecondaryCbFuncType* wrap = nullptr;
+    uint32_t gas = 0;
+};
+
+using WasmUserData = std::pair<HFRef, WasmImportFunc>;
+// string - import function name
+using ImportVec = std::unordered_map<std::string_view, WasmUserData>;
+
+template <int N, int C, typename Mpl>
+void
+WasmImpArgs(WasmImportFunc& e)
+{
+    if constexpr (N < C)
+    {
+        using at = boost::mpl::at_c<Mpl, N>::type;
+        if constexpr (std::is_pointer_v<at> || std::is_same_v<at, std::int32_t>)
+        {
+            e.params.push_back(WasmTypes::WtI32);
+        }
+        else if constexpr (std::is_same_v<at, std::int64_t>)
+        {
+            e.params.push_back(WasmTypes::WtI64);
+        }
+        else
+        {
+            static_assert(std::is_pointer_v<at>, "Unsupported argument type");
+        }
+
+        return WasmImpArgs<N + 1, C, Mpl>(e);
+    }
+}
+
+template <typename>
+inline constexpr bool wasmDependentFalse = false;
+
+template <typename Rt>
+void
+WasmImpRet(WasmImportFunc& e)
+{
+    if constexpr (std::is_pointer_v<Rt> || std::is_same_v<Rt, std::int32_t>)
+    {
+        e.result = WasmTypes::WtI32;
+    }
+    else if constexpr (std::is_same_v<Rt, std::int64_t>)
+    {
+        e.result = WasmTypes::WtI64;
+    }
+    else if constexpr (std::is_void_v<Rt>)
+    {
+        e.result.reset();
+    }
+    else
+    {
+        static_assert(wasmDependentFalse<Rt>, "Unsupported return type");
+    }
+}
+
+template <typename F>
+void
+WasmImpFuncHelper(WasmImportFunc& e)
+{
+    using rt = bft::result_type<F>::type;
+    using pt = bft::parameter_types<F>::type;
+    // typename boost::mpl::at_c<mpl, N>::type
+
+    WasmImpRet<rt>(e);
+    WasmImpArgs<0, bft::function_arity<F>::value, pt>(e);
+    // WasmImpWrap(e, std::forward<F>(f));
+}
+
+// imp_name - string literal, must have static lifetime
+template <typename F>
+void
+WasmImpFunc(
+    ImportVec& v,
+    std::string_view impName,
+    wasmSecondaryCbFuncType* fWrap,
+    HostFunctions& hf,
+    uint32_t gas = 0)
+{
+    WasmImportFunc e;
+    e.name = impName;
+    e.wrap = fWrap;
+    e.gas = gas;
+    WasmImpFuncHelper<F>(e);
+    v.emplace(impName, std::make_pair(HFRef(hf), std::move(e)));
+}
+
+#define WASM_IMPORT_FUNC(v, f, ...) WasmImpFunc<f##_proto>(v, #f, &f##_wrap, ##__VA_ARGS__)
+
+// n - string literal name, must have static lifetime
+#define WASM_IMPORT_FUNC2(v, f, n, ...) WasmImpFunc<f##_proto>(v, n, &f##_wrap, ##__VA_ARGS__)
+
+}  // namespace xrpl

include/xrpl/tx/wasm/WasmVM.h

@@ -0,0 +1,97 @@
+#pragma once
+
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/protocol/TER.h>
+#include <xrpl/tx/wasm/HostFunc.h>
+#include <xrpl/tx/wasm/WasmCommon.h>
+#include <xrpl/tx/wasm/WasmImportsHelper.h>
+
+#include <cstdint>
+#include <expected>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace xrpl {
+
+std::string_view inline constexpr wEnv = "env";
+std::string_view inline constexpr wHostLib = "host_lib";
+std::string_view inline constexpr wMem = "memory";
+std::string_view inline constexpr wStore = "store";
+std::string_view inline constexpr wLoad = "load";
+std::string_view inline constexpr wSize = "size";
+std::string_view inline constexpr wAlloc = "allocate";
+std::string_view inline constexpr wDealloc = "deallocate";
+std::string_view inline constexpr wProcExit = "proc_exit";
+
+std::string_view inline constexpr escrowFunctionName = "escrow_finish";
+
+uint32_t inline constexpr maxPages = 128;  // 8MB = 64KB*128
+
+class WasmiEngine;
+
+class WasmEngine
+{
+    std::unique_ptr<WasmiEngine> const impl_;
+
+    WasmEngine();
+
+public:
+    WasmEngine(WasmEngine const&) = delete;
+    WasmEngine(WasmEngine&&) = delete;
+    WasmEngine&
+    operator=(WasmEngine const&) = delete;
+    WasmEngine&
+    operator=(WasmEngine&&) = delete;
+
+    static WasmEngine&
+    instance();
+
+    std::expected<WasmResult<int32_t>, WasmTER>
+    run(Bytes const& wasmCode,
+        HostFunctions& hfs,
+        int64_t gasLimit,
+        std::string_view funcName = {},
+        std::vector<WasmParam> const& params = {},
+        ImportVec const& imports = {},
+        beast::Journal j = beast::Journal{beast::Journal::getNullSink()});
+
+    NotTEC
+    check(
+        Bytes const& wasmCode,
+        HostFunctions& hfs,
+        std::string_view funcName,
+        std::vector<WasmParam> const& params = {},
+        ImportVec const& imports = {},
+        beast::Journal j = beast::Journal{beast::Journal::getNullSink()});
+
+    // Host functions helper functionality
+    void*
+    newTrap(std::string const& txt = std::string());
+
+    [[nodiscard]] beast::Journal
+    getJournal() const;
+};
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ImportVec
+createWasmImport(HostFunctions& hfs);
+
+std::expected<EscrowResult, WasmTER>
+runEscrowWasm(
+    Bytes const& wasmCode,
+    HostFunctions& hfs,
+    int64_t gasLimit,
+    std::string_view funcName = escrowFunctionName,
+    std::vector<WasmParam> const& params = {});
+
+NotTEC
+preflightEscrowWasm(
+    Bytes const& wasmCode,
+    HostFunctions& hfs,
+    std::string_view funcName = escrowFunctionName,
+    std::vector<WasmParam> const& params = {});
+
+}  // namespace xrpl

include/xrpl/tx/wasm/WasmiVM.h

@@ -0,0 +1,462 @@
+#pragma once
+
+#include <xrpl/basics/contract.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/protocol/Protocol.h>
+#include <xrpl/protocol/TER.h>
+#include <xrpl/tx/wasm/HostFunc.h>
+#include <xrpl/tx/wasm/WasmCommon.h>
+#include <xrpl/tx/wasm/WasmImportsHelper.h>
+#include <xrpl/tx/wasm/WasmVM.h>
+
+#include <wasm.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <expected>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace xrpl {
+
+template <class T, void (*Create)(T*, size_t), void (*Destroy)(T*)>
+class WasmVec
+{
+    using TD = std::remove_pointer_t<decltype(T::data)>;
+    T vec_;
+
+public:
+    WasmVec(size_t s = 0) : vec_ WASM_EMPTY_VEC
+    {
+        if (s > 0)
+            Create(&vec_, s);  // zeroes memory
+    }
+
+    ~WasmVec()
+    {
+        clear();
+    }
+
+    WasmVec(WasmVec const&) = delete;
+    WasmVec&
+    operator=(WasmVec const&) = delete;
+
+    WasmVec(WasmVec&& other) noexcept : vec_ WASM_EMPTY_VEC
+    {
+        *this = std::move(other);
+    }
+
+    WasmVec&
+    operator=(WasmVec&& other) noexcept
+    {
+        if (this != &other)
+        {
+            clear();
+            vec_ = other.vec_;
+            other.vec_ = WASM_EMPTY_VEC;
+        }
+        return *this;
+    }
+
+    void
+    clear()
+    {
+        Destroy(&vec_);  // call destructor for every elements too
+        vec_ = WASM_EMPTY_VEC;
+    }
+
+    T
+    release()
+    {
+        T result = vec_;
+        vec_ = WASM_EMPTY_VEC;
+        return result;
+    }
+
+    T*
+    get()
+    {
+        return &vec_;
+    }
+
+    [[nodiscard]] T const*
+    get() const
+    {
+        return &vec_;
+    }
+
+    TD&
+    operator[](size_t i)
+    {
+        if (i >= vec_.size)
+            Throw<std::runtime_error>("Out of bound");
+        return vec_.data[i];
+    }
+
+    TD const&
+    operator[](size_t i) const
+    {
+        if (i >= vec_.size)
+            Throw<std::runtime_error>("Out of bound");
+        return vec_.data[i];
+    }
+
+    [[nodiscard]] size_t
+    size() const
+    {
+        return vec_.size;
+    }
+
+    [[nodiscard]] bool
+    empty() const
+    {
+        return vec_.size == 0u;
+    }
+};
+
+using WasmValtypeVec =
+    WasmVec<wasm_valtype_vec_t, &wasm_valtype_vec_new_uninitialized, &wasm_valtype_vec_delete>;
+using WasmValVec = WasmVec<wasm_val_vec_t, &wasm_val_vec_new_uninitialized, &wasm_val_vec_delete>;
+using WasmExternVec =
+    WasmVec<wasm_extern_vec_t, &wasm_extern_vec_new_uninitialized, &wasm_extern_vec_delete>;
+using WasmExporttypeVec = WasmVec<
+    wasm_exporttype_vec_t,
+    &wasm_exporttype_vec_new_uninitialized,
+    &wasm_exporttype_vec_delete>;
+using WasmImporttypeVec = WasmVec<
+    wasm_importtype_vec_t,
+    &wasm_importtype_vec_new_uninitialized,
+    &wasm_importtype_vec_delete>;
+
+struct WasmiResult
+{
+    WasmValVec r;
+    // Set iff the call trapped. Holds the TER the trap was classified into
+    // (tecINTERNAL / tecOUT_OF_GAS / tecFAILED_PROCESSING); see
+    // WasmiEngine::call. std::nullopt means the call returned normally.
+    std::optional<TER> ter;
+
+    WasmiResult(unsigned n = 0) : r(n)
+    {
+    }
+
+    WasmiResult() = delete;
+    ~WasmiResult() = default;
+    WasmiResult(WasmiResult&& o) = default;
+    WasmiResult&
+    operator=(WasmiResult&& o) = default;
+};
+
+using ModulePtr = std::unique_ptr<wasm_module_t, decltype(&wasm_module_delete)>;
+using InstancePtr = std::unique_ptr<wasm_instance_t, decltype(&wasm_instance_delete)>;
+using EnginePtr = std::unique_ptr<wasm_engine_t, decltype(&wasm_engine_delete)>;
+using StorePtr = std::unique_ptr<wasm_store_t, decltype(&wasm_store_delete)>;
+
+using FuncInfo = std::pair<wasm_func_t const*, wasm_functype_t const*>;
+
+class InstanceWrapper
+{
+    wasm_store_t* store_ = nullptr;
+    WasmExternVec exports_;
+    mutable int memIdx_ = -1;
+    InstancePtr instance_;
+    beast::Journal j_ = beast::Journal(beast::Journal::getNullSink());
+    std::int64_t transferLimit_ = kWasmTransferLimit;
+
+private:
+    static InstancePtr
+    init(
+        StorePtr& s,
+        ModulePtr& m,
+        WasmExternVec& expt,
+        WasmExternVec const& imports,
+        beast::Journal j);
+
+public:
+    InstanceWrapper() : instance_(nullptr, &wasm_instance_delete) {};
+
+    InstanceWrapper(InstanceWrapper const&) = delete;
+
+    InstanceWrapper(InstanceWrapper&& o) : instance_(nullptr, &wasm_instance_delete)
+    {
+        *this = std::move(o);  // LCOV_EXCL_LINE
+    }
+
+    InstanceWrapper(StorePtr& s, ModulePtr& m, WasmExternVec const& imports, beast::Journal j)
+        : store_(s.get()), instance_(init(s, m, exports_, imports, j)), j_(j)
+    {
+    }
+
+    InstanceWrapper&
+    operator=(InstanceWrapper&& o);
+
+    InstanceWrapper&
+    operator=(InstanceWrapper const&) = delete;
+
+    operator bool() const
+    {
+        return static_cast<bool>(instance_);
+    }
+
+    FuncInfo
+    getFunc(std::string_view funcName, WasmExporttypeVec const& exportTypes) const;
+
+    Wmem
+    getMem() const;
+
+    std::int64_t
+    getGas() const;
+
+    std::int64_t
+    setGas(std::int64_t) const;
+
+    std::int64_t
+    getTransferLimit() const;
+
+    std::int64_t
+    setTransferLimit(std::int64_t);
+};
+
+class ModuleWrapper
+{
+    ModulePtr module_;
+    InstanceWrapper instanceWrap_;
+    WasmExporttypeVec exportTypes_;
+    beast::Journal j_ = beast::Journal(beast::Journal::getNullSink());
+
+public:
+    // LCOV_EXCL_START
+    ModuleWrapper() : module_(nullptr, &wasm_module_delete)
+    {
+    }
+
+    ModuleWrapper(ModuleWrapper&& o) : module_(nullptr, &wasm_module_delete)
+    {
+        *this = std::move(o);
+    }
+    // LCOV_EXCL_STOP
+
+    ModuleWrapper&
+    operator=(ModuleWrapper&& o);
+    ModuleWrapper(
+        StorePtr& s,
+        Bytes const& wasmBin,
+        bool instantiate,
+        ImportVec const& imports,
+        beast::Journal j);
+    ~ModuleWrapper() = default;
+
+    operator bool() const
+    {
+        return instanceWrap_;
+    }
+
+    FuncInfo
+    getFunc(std::string_view funcName) const
+    {
+        return instanceWrap_.getFunc(funcName, exportTypes_);
+    }
+
+    wasm_functype_t const*
+    getFuncType(std::string_view funcName) const;
+
+    Wmem
+    getMem() const
+    {
+        return instanceWrap_.getMem();
+    }
+
+    InstanceWrapper&
+    getInstance(int i = 0)
+    {
+        return instanceWrap_;
+    }
+
+    InstanceWrapper const&
+    getInstance(int i = 0) const
+    {
+        return instanceWrap_;
+    }
+
+    int
+    addInstance(StorePtr& s, WasmExternVec const& imports)
+    {
+        instanceWrap_ = {s, module_, imports, j_};
+        return 0;
+    }
+
+    std::int64_t
+    getGas() const
+    {
+        return instanceWrap_ ? instanceWrap_.getGas() : -1;
+    }
+
+private:
+    static ModulePtr
+    init(StorePtr& s, Bytes const& wasmBin, beast::Journal j);
+
+    WasmExternVec
+    buildImports(StorePtr& s, ImportVec const& imports) const;
+};
+
+class WasmiEngine
+{
+    EnginePtr engine_;
+    StorePtr store_;
+    std::unique_ptr<ModuleWrapper> moduleWrap_;
+    beast::Journal j_ = beast::Journal(beast::Journal::getNullSink());
+
+    std::mutex m_;  // 1 instance mutex
+
+public:
+    WasmiEngine() : engine_(init()), store_(nullptr, &wasm_store_delete)
+    {
+    }
+
+    ~WasmiEngine() = default;
+
+    static EnginePtr
+    init();
+
+    std::expected<WasmResult<int32_t>, WasmTER>
+    run(Bytes const& wasmCode,
+        HostFunctions& hfs,
+        int64_t gas,
+        std::string_view funcName,
+        std::vector<WasmParam> const& params,
+        ImportVec const& imports,
+        beast::Journal j);
+
+    NotTEC
+    check(
+        Bytes const& wasmCode,
+        HostFunctions& hfs,
+        std::string_view funcName,
+        std::vector<WasmParam> const& params,
+        ImportVec const& imports,
+        beast::Journal j);
+
+    [[nodiscard]] std::int64_t
+    getGas() const
+    {
+        return moduleWrap_ ? moduleWrap_->getGas() : -1;  // LCOV_EXCL_LINE
+    }
+
+    // Host functions helper functionality
+    wasm_trap_t*
+    newTrap(std::string const& msg);
+
+    // LCOV_EXCL_START
+    [[nodiscard]] beast::Journal
+    getJournal() const
+    {
+        return j_;
+    }
+    // LCOV_EXCL_STOP
+
+private:
+    [[nodiscard]] InstanceWrapper&
+    getRT(int m = 0, int i = 0) const
+    {
+        if (!moduleWrap_)
+            Throw<std::runtime_error>("no module");
+        return moduleWrap_->getInstance(i);
+    }
+
+    [[nodiscard]] Wmem
+    getMem() const
+    {
+        return moduleWrap_ ? moduleWrap_->getMem() : Wmem();
+    }
+
+    std::expected<WasmResult<int32_t>, WasmTER>
+    runHlp(
+        Bytes const& wasmCode,
+        HostFunctions& hfs,
+        int64_t gas,
+        std::string_view funcName,
+        std::vector<WasmParam> const& params,
+        ImportVec const& imports,
+        beast::Journal j);
+
+    NotTEC
+    checkHlp(
+        Bytes const& wasmCode,
+        HostFunctions& hfs,
+        std::string_view funcName,
+        std::vector<WasmParam> const& params,
+        ImportVec const& imports,
+        beast::Journal j);
+
+    int
+    addModule(Bytes const& wasmCode, bool instantiate, ImportVec const& imports, int64_t gas);
+    void
+    clearModules();
+
+    // int  addInstance();
+
+    int32_t
+    runFunc(std::string_view const funcName, int32_t p);
+
+    int32_t
+    makeModule(Bytes const& wasmCode, WasmExternVec const& imports = {});
+
+    [[nodiscard]] FuncInfo
+    getFunc(std::string_view funcName) const
+    {
+        return moduleWrap_->getFunc(funcName);
+    }
+
+    static std::vector<wasm_val_t>
+    convertParams(std::vector<WasmParam> const& params);
+
+    static int
+    compareParamTypes(wasm_valtype_vec_t const* ftp, std::vector<wasm_val_t> const& p);
+
+    static void
+    addParam(std::vector<wasm_val_t>& in, int32_t p);
+    static void
+    addParam(std::vector<wasm_val_t>& in, int64_t p);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(std::string_view func, Types&&... args);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(FuncInfo const& f, Types&&... args);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(FuncInfo const& f, std::vector<wasm_val_t>& in);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(FuncInfo const& f, std::vector<wasm_val_t>& in, std::int32_t p, Types&&... args);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(FuncInfo const& f, std::vector<wasm_val_t>& in, std::int64_t p, Types&&... args);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(
+        FuncInfo const& f,
+        std::vector<wasm_val_t>& in,
+        uint8_t const* d,
+        int32_t sz,
+        Types&&... args);
+
+    template <int NR, class... Types>
+    inline WasmiResult
+    call(FuncInfo const& f, std::vector<wasm_val_t>& in, Bytes const& p, Types&&... args);
+};
+
+}  // namespace xrpl

nix/ci-env.nix

@@ -7,8 +7,10 @@ let
   inherit (import ./packages.nix { inherit pkgs; })
     commonPackages
     gccPackage
+    gccVersion
     llvmPackages
     llvmVersion
+    mkVersionedToolLinks
     ;
 
   # Underlying compiler toolchains to wrap (versions pinned in packages.nix).
@@ -127,6 +129,25 @@ in
       customGcov
       customClangForCiEnv
       customBinutils
+      (mkVersionedToolLinks {
+        name = "gcc";
+        package = customGcc;
+        version = gccVersion;
+        tools = [
+          "gcc"
+          "g++"
+          "cpp"
+        ];
+      })
+      (mkVersionedToolLinks {
+        name = "clang";
+        package = customClang;
+        version = llvmVersion;
+        tools = [
+          "clang"
+          "clang++"
+        ];
+      })
       # CA certificate bundle so HTTPS clients (git, curl, conan) can verify
       # TLS connections without ca-certificates being installed in the system.
       pkgs.cacert

nix/devshell.nix

@@ -3,7 +3,9 @@ let
   inherit (import ./packages.nix { inherit pkgs; })
     commonPackages
     gccVersion
+    llvmVersion
     llvmPackages
+    mkVersionedToolLinks
     ;
 
   # Plain nixpkgs stdenvs — no custom glibc, unlike ci-env.nix.
@@ -15,6 +17,8 @@ let
     {
       stdenv,
       compilerName,
+      version ? null,
+      versionedTools ? [ ],
     }:
     let
       compilerVersion =
@@ -25,9 +29,15 @@ let
             echo "Compiler: "
             ${compilerName} --version
           '';
+      versionedLinks = pkgs.lib.optional (version != null) (mkVersionedToolLinks {
+        name = compilerName;
+        package = stdenv.cc;
+        inherit version;
+        tools = versionedTools;
+      });
     in
     (pkgs.mkShell.override { inherit stdenv; }) {
-      packages = commonPackages;
+      packages = commonPackages ++ versionedLinks;
       shellHook = ''
         echo "Welcome to xrpld development shell";
         ${compilerVersion}
@@ -41,11 +51,22 @@ rec {
   gcc = makeShell {
     stdenv = gccStdenv;
     compilerName = "gcc";
+    version = gccVersion;
+    versionedTools = [
+      "gcc"
+      "g++"
+      "cpp"
+    ];
   };
 
   clang = makeShell {
     stdenv = clangStdenv;
     compilerName = "clang";
+    version = llvmVersion;
+    versionedTools = [
+      "clang"
+      "clang++"
+    ];
   };
 
   # Nix provides no compiler; use the one from your system (e.g. Apple Clang).

nix/docker/Dockerfile

@@ -12,6 +12,7 @@ COPY nix/packages.nix /tmp/build/nix/packages.nix
 COPY nix/utils.nix /tmp/build/nix/utils.nix
 COPY flake.nix /tmp/build/
 COPY flake.lock /tmp/build/
+COPY rust-toolchain.toml /tmp/build/
 WORKDIR /tmp/build
 
 FROM builder-source AS builder
@@ -75,9 +76,13 @@ COPY bin/check-tools.sh /tmp/check-tools.sh
 RUN /tmp/check-tools.sh
 
 # Sanity-check that the g++/clang++ are able to build binaries, including sanitizer-instrumented ones.
-COPY nix/docker/test_files/cpp_sources/ /tmp/cpp_sources/
-COPY nix/docker/test_files/compile-cpp-sources.sh /tmp/compile-cpp-sources.sh
-RUN /tmp/compile-cpp-sources.sh /tmp/cpp_sources /tmp/bins
+COPY nix/docker/test_files/cpp/ /tmp/test_files/cpp/
+RUN /tmp/test_files/cpp/compile-sources.sh /tmp/test_files/cpp/sources /tmp/cpp-bins
+
+# Sanity-check that rustc is able to build binaries, including ones that rely on
+# the runtime overflow check.
+COPY nix/docker/test_files/rust/ /tmp/test_files/rust/
+RUN /tmp/test_files/rust/compile-sources.sh /tmp/test_files/rust/sources /tmp/rust-bins
 
 # Tester: start from a clean BASE_IMAGE, install sanitizer runtime libraries,
 # and run the compiled test binaries to verify they execute correctly.
@@ -94,15 +99,18 @@ SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
 
 # Sanity-check that the built binaries run correctly in the vanilla base image, with the necessary sanitizer runtime libraries installed.
 COPY bin/install-sanitizer-libs.sh /tmp/install-sanitizer-libs.sh
-COPY nix/docker/test_files/run-test-binaries.sh /tmp/run-test-binaries.sh
-COPY --from=final /tmp/bins /tmp/bins
+COPY nix/docker/test_files/cpp/run-binaries.sh /tmp/test_files/cpp/run-binaries.sh
+COPY nix/docker/test_files/rust/run-binaries.sh /tmp/test_files/rust/run-binaries.sh
+COPY --from=final /tmp/cpp-bins /tmp/cpp-bins
+COPY --from=final /tmp/rust-bins /tmp/rust-bins
 
 RUN <<EOF
 if echo "${BASE_IMAGE}" | grep -qiE 'nixos'; then
     echo "Skipping runnning binaries on NixOS."
 else
     /tmp/install-sanitizer-libs.sh
-    /tmp/run-test-binaries.sh /tmp/bins
+    /tmp/test_files/cpp/run-binaries.sh /tmp/cpp-bins
+    /tmp/test_files/rust/run-binaries.sh /tmp/rust-bins
 fi
 touch /tmp/tests-passed
 EOF

nix/docker/README.md

@@ -42,9 +42,14 @@ work without `ca-certificates` being installed in the base image.
    - installs the dynamic linker if the base image lacks one (see
      [How libc is handled](#how-libc-is-handled)),
    - runs [`bin/check-tools.sh`](../../bin/check-tools.sh) to verify every
-     expected tool is present and runnable, and
+     expected tool is present and runnable.
    - compiles the C++ test programs in
-     [`test_files/`](./test_files) with both `g++` and `clang++`, and sanitizers.
+     [`test_files/cpp/sources/`](./test_files/cpp/sources) with both `g++` and
+     `clang++`, and sanitizers, and
+   - compiles the Rust test programs in
+     [`test_files/rust/sources/`](./test_files/rust/sources) with `rustc`, and
+     builds the [`test_files/rust/proc_macro/`](./test_files/rust/proc_macro)
+     workspace with `cargo` to exercise proc-macro dylib loading.
 3. **`tester`** — Start again from a clean `BASE_IMAGE` (no Nix toolchain),
    install only the sanitizer runtime libraries
    ([`install-sanitizer-libs.sh`](./install-sanitizer-libs.sh)), and run the
@@ -73,18 +78,23 @@ toolchain being present at runtime. Two pieces make that work:
   [`loader-path.sh`](./loader-path.sh) reports the expected loader path for the
   current architecture, so we can patch the binaries to use the correct loader.
 
-The build then verifies all of this end to end: the test programs in
-`test_files/` (a regular binary plus ASan/TSan/UBSan variants) are compiled in
-`final`, their `PT_INTERP` is patched to the target loader, and they are run in
-the clean `tester` stage to confirm each emits the expected sanitizer
-diagnostic on a stock base image.
+The build then verifies all of this end to end, and the C++ and Rust programs
+go through the same pipeline: each is compiled in `final`, has its `PT_INTERP`
+patched to the target loader, and is then run in the clean `tester` stage to
+confirm it emits the expected diagnostic on a stock base image. The C++ programs
+are in `test_files/cpp/sources/` (a regular binary plus ASan/TSan/UBSan
+variants); the Rust programs are in `test_files/rust/sources/` (a hello binary
+plus panic and overflow-check variants), plus the `test_files/rust/proc_macro/`
+workspace — a crate whose compilation additionally loads a proc-macro dylib, and
+whose resulting binary is patched and run like the others.
 
 ## Files
 
-| File                                                                    | Purpose                                                                       |
-| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`./Dockerfile`](./Dockerfile)                                          | Multi-stage build described above.                                            |
-| [`./loader-path.sh`](./loader-path.sh)                                  | Print the dynamic-linker (`PT_INTERP`) path for the current architecture.     |
-| [`./test_files/`](./test_files)                                         | C++ sources and scripts to compile and run the sanitizer smoke tests.         |
-| [`/bin/check-tools.sh`](../../bin/check-tools.sh)                       | Verify every expected tools are present and runnable.                         |
-| [`/bin/install-sanitizer-libs.sh`](../../bin/install-sanitizer-libs.sh) | Install `libasan`/`libtsan`/`libubsan` runtimes on the supported base images. |
+| File                                                                    | Purpose                                                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [`./Dockerfile`](./Dockerfile)                                          | Multi-stage build described above.                                                   |
+| [`./loader-path.sh`](./loader-path.sh)                                  | Print the dynamic-linker (`PT_INTERP`) path for the current architecture.            |
+| [`./test_files/cpp/`](./test_files/cpp)                                 | C++ sanitizer smoke test: sources + compile/run scripts.                             |
+| [`./test_files/rust/`](./test_files/rust)                               | Rust smoke test: rustc sources + a cargo proc-macro workspace + compile/run scripts. |
+| [`/bin/check-tools.sh`](../../bin/check-tools.sh)                       | Verify every expected tools are present and runnable.                                |
+| [`/bin/install-sanitizer-libs.sh`](../../bin/install-sanitizer-libs.sh) | Install `libasan`/`libtsan`/`libubsan` runtimes on the supported base images.        |

nix/docker/test_files/rust/compile-sources.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Compile all Rust test binaries during the Docker image build.
+# Each binary has the target system's ELF PT_INTERP (dynamic-linker path)
+# baked in so it can run on the (potentially minimal) final BASE_IMAGE.
+
+set -eo pipefail
+
+src_dir="${1:?usage: $0 <src_dir> <dst_dir>}"
+dst_dir="${2:?usage: $0 <src_dir> <dst_dir>}"
+
+loader="$(/tmp/loader-path.sh)"
+
+mkdir -p "${dst_dir}"
+
+function compile() {
+    local name="${1}"
+    local extra_flags="${2:-}"
+
+    local src="${src_dir}/${name}.rs"
+    local binary="${dst_dir}/${name}"
+
+    echo "=== Compiling ${name} with rustc ==="
+    # -O optimizes (opt-level 2); Rust statically links its own std, so the
+    # only dynamic dependency left is the system glibc (+ libgcc_s), exactly
+    # like the C++ binaries.
+    local compile_cmd="rustc --edition 2021 -O -g ${extra_flags} \
+        ${src} -o ${binary}"
+    echo "Compile cmd: ${compile_cmd}"
+    eval "${compile_cmd}"
+
+    echo "=== Patching ${binary} to use ${loader} as PT_INTERP ==="
+    local patch_cmd="patchelf --set-interpreter ${loader} --remove-rpath ${binary}"
+    echo "Patch cmd: ${patch_cmd}"
+    eval "${patch_cmd}"
+}
+
+# `-O` disables overflow checks by default, so `overflow` re-enables them
+# explicitly to exercise the runtime overflow check.
+compile hello
+compile panic
+compile overflow "-C overflow-checks=on"
+
+function compile_proc_macro() {
+    local proj="${src_dir}/../proc_macro"
+
+    echo "=== Building proc-macro workspace (cargo) ==="
+    cargo build --manifest-path "${proj}/Cargo.toml" --offline
+
+    local built="${proj}/target/debug/test_macro"
+    if [ ! -f "${built}" ]; then
+        echo "ERROR: built test_macro binary not found at ${built}" >&2
+        exit 1
+    fi
+
+    local binary="${dst_dir}/proc_macro"
+    cp "${built}" "${binary}"
+
+    echo "=== Patching ${binary} to use ${loader} as PT_INTERP ==="
+    patchelf --set-interpreter "${loader}" --remove-rpath "${binary}"
+
+    rm -rf "${proj}/target"
+}
+
+compile_proc_macro
+
+echo "=== All binaries compiled ==="
+
+ls -la "${dst_dir}"

nix/docker/test_files/rust/proc_macro/Cargo.lock

@@ -0,0 +1,14 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "echo_macro"
+version = "0.0.0"
+
+[[package]]
+name = "test_macro"
+version = "0.0.0"
+dependencies = [
+ "echo_macro",
+]

nix/docker/test_files/rust/proc_macro/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["echo_macro", "test_macro"]

nix/docker/test_files/rust/proc_macro/echo_macro/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "echo_macro"
+version = "0.0.0"
+edition = "2024"
+publish = false
+
+[lib]
+proc-macro = true

nix/docker/test_files/rust/proc_macro/echo_macro/src/lib.rs

@@ -0,0 +1,6 @@
+use proc_macro::TokenStream;
+
+#[proc_macro]
+pub fn define_echo(item: TokenStream) -> TokenStream {
+    format!("fn echo() -> u32 {{ {item} }}").parse().unwrap()
+}

nix/docker/test_files/rust/proc_macro/test_macro/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "test_macro"
+version = "0.0.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+echo_macro = { path = "../echo_macro" }

nix/docker/test_files/rust/proc_macro/test_macro/src/main.rs

@@ -0,0 +1,9 @@
+use echo_macro::define_echo;
+
+define_echo!(42);
+
+fn main() {
+    let a = echo();
+    println!("proc-macro answer = {a}");
+    assert_eq!(a, 42, "proc-macro expansion produced the wrong value");
+}

nix/docker/test_files/rust/run-binaries.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Run pre-compiled Rust binaries and confirm each emits its expected diagnostic.
+# Binaries must already exist in <bins_dir> as <name> for name in
+# {hello,panic,overflow,proc_macro}.
+
+set -eo pipefail
+
+bins_dir="${1:?usage: $0 <bins_dir>}"
+
+failed_binaries=()
+
+# Run a binary and verify its exit code and output.
+# Usage: run <binary> <expected_output> <expected_rc>
+function run() {
+    local binary="${1}"
+    local expected_output="${2}"
+    local expected_rc="${3}"
+
+    local out_file
+    out_file="$(mktemp)"
+
+    echo "=== Run ${binary} ==="
+    set +e
+    "${binary}" >"${out_file}" 2>&1
+    local rc=$?
+    set -e
+
+    cat "${out_file}"
+
+    local failed=0
+    if [ "${expected_rc}" = "nonzero" ]; then
+        if [ "${rc}" -eq 0 ]; then
+            echo "ERROR: expected non-zero exit code from ${binary}, got ${rc}" >&2
+            failed=1
+        fi
+    elif [ "${rc}" -ne "${expected_rc}" ]; then
+        echo "ERROR: expected exit code ${expected_rc} from ${binary}, got ${rc}" >&2
+        failed=1
+    fi
+
+    if ! grep -q "${expected_output}" "${out_file}"; then
+        echo "ERROR: expected '${expected_output}' from ${binary}" >&2
+        failed=1
+    fi
+
+    if [ "${failed}" -eq 0 ]; then
+        echo "OK: '${expected_output}' detected"
+    else
+        failed_binaries+=("${binary}")
+    fi
+}
+
+declare -A expect=(
+    [hello]="Hello from main thread"
+    [panic]="explicit panic from test"
+    [overflow]="attempt to add with overflow"
+    [proc_macro]="proc-macro answer = 42"
+)
+
+for name in hello panic overflow proc_macro; do
+    binary="${bins_dir}/${name}"
+
+    if [ "${name}" = "hello" ] || [ "${name}" = "proc_macro" ]; then
+        expected_rc=0
+    else
+        expected_rc=nonzero
+    fi
+    run "${binary}" "${expect[$name]}" "${expected_rc}"
+done
+
+if [ "${#failed_binaries[@]}" -gt 0 ]; then
+    echo "ERROR: the following binaries failed:" >&2
+    printf '  %s\n' "${failed_binaries[@]}" >&2
+    exit 1
+fi

nix/docker/test_files/rust/sources/hello.rs

@@ -0,0 +1,16 @@
+use std::thread;
+
+fn main() {
+    const NUM_THREADS: usize = 10;
+    let mut handles = Vec::with_capacity(NUM_THREADS);
+    for id in 0..NUM_THREADS {
+        handles.push(thread::spawn(move || {
+            println!("Hello from thread {id}");
+        }));
+    }
+    for handle in handles {
+        handle.join().expect("worker thread panicked");
+    }
+
+    println!("Hello from main thread");
+}

nix/docker/test_files/rust/sources/overflow.rs

@@ -0,0 +1,13 @@
+use std::hint::black_box;
+
+// Rust analogue of the C++ UBSan check: with overflow checks enabled the
+// compiler inserts a runtime check that panics on signed integer overflow.
+// `black_box` keeps the operands opaque so the addition is evaluated at
+// runtime rather than being rejected by the compile-time overflow lint.
+fn main() {
+    let max = black_box(i32::MAX);
+    let one = black_box(1);
+    println!("Current max: {max}");
+    let overflowed = max + one;
+    println!("Overflowed result: {overflowed}");
+}

nix/docker/test_files/rust/sources/panic.rs

@@ -0,0 +1,5 @@
+fn main() {
+    // Verify the panic runtime works: a panic must print its message to stderr
+    // and exit with a non-zero status (Rust's default panic exit code is 101).
+    panic!("explicit panic from test");
+}

nix/packages.nix

@@ -15,6 +15,55 @@ let
   runClangTidy = pkgs.writeShellScriptBin "run-clang-tidy" ''
     exec ${pkgs.python3}/bin/python3 ${llvmPackages.clang-unwrapped}/bin/run-clang-tidy "$@"
   '';
+
+  rustToolchain = pkgs.rust-bin.fromRustupToolchainFile ../rust-toolchain.toml;
+
+  # Nix wraps its toolchain so that binaries are exposed only under unsuffixed
+  # names (gcc, g++, clang-tidy, ...). Several tools probe for a
+  # version-suffixed name first and fall back to a system binary on the PATH
+  # when Nix doesn't provide it:
+  #   - Conan's Boost recipe looks up `g++-<major>` before plain `g++`.
+  #   - bin/pre-commit/clang_tidy_check.py looks up `run-clang-tidy-<v>` and
+  #     `clang-apply-replacements-<v>` before the unsuffixed names.
+  # On a host that also has the matching system binary (e.g. Ubuntu's
+  # `/usr/bin/g++-15` or `clang-tidy-22`) the probe escapes Nix and mixes a
+  # system tool into the Nix environment. Generate version-suffixed symlinks
+  # next to a package's tools so those probes resolve to the Nix ones.
+  #
+  # Compiler links must point at whichever compiler is active in a given
+  # environment (the plain stdenv compiler in the dev shell, the custom-glibc
+  # wrappers in ci-env.nix), so those callers pass their own `package`; the
+  # clang tooling is environment-independent and is linked in commonPackages.
+  mkVersionedToolLinks =
+    {
+      name,
+      package,
+      version,
+      tools,
+    }:
+    pkgs.linkFarm "${name}-${toString version}-versioned-links" (
+      map (tool: {
+        name = "bin/${tool}-${toString version}";
+        path = "${package}/bin/${tool}";
+      }) tools
+    );
+
+  clangToolLinks = mkVersionedToolLinks {
+    name = "clang-tools";
+    package = clangTools;
+    version = llvmVersion;
+    tools = [
+      "clang-tidy"
+      "clang-apply-replacements"
+      "clang-format"
+    ];
+  };
+  runClangTidyLink = mkVersionedToolLinks {
+    name = "run-clang-tidy";
+    package = runClangTidy;
+    version = llvmVersion;
+    tools = [ "run-clang-tidy" ];
+  };
 in
 {
   inherit
@@ -22,9 +71,12 @@ in
     llvmVersion
     gccPackage
     llvmPackages
+    mkVersionedToolLinks
     ;
 
   commonPackages = with pkgs; [
+    clangToolLinks
+    runClangTidyLink
     ccache
     clangbuildanalyzer
     clangTools
@@ -62,5 +114,11 @@ in
     runClangTidy
     vim
     zip
+    # Rust packages
+    cargo-audit
+    cargo-llvm-cov
+    cargo-nextest
+    corrosion
+    rustToolchain
   ];
 }

nix/utils.nix

@@ -1,4 +1,8 @@
-{ nixpkgs, nixpkgs-custom-glibc }:
+{
+  nixpkgs,
+  nixpkgs-custom-glibc,
+  rust-overlay,
+}:
 function:
 nixpkgs.lib.genAttrs
   [
@@ -10,7 +14,12 @@ nixpkgs.lib.genAttrs
   (
     system:
     function {
-      pkgs = import nixpkgs { inherit system; };
+      # rust-overlay adds `pkgs.rust-bin`, from which we build the pinned Rust
+      # toolchain (see packages.nix). Consumed by both the CI image and dev shell.
+      pkgs = import nixpkgs {
+        inherit system;
+        overlays = [ (import rust-overlay) ];
+      };
       # glibc 2.31 — matches the system libc on Ubuntu 20.04 LTS. Sourced
       # from the nixpkgs snapshot pinned via the `nixpkgs-custom-glibc`
       # flake input, so the build uses the compiler from that snapshot

rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.95"
+components = ["rustfmt", "clippy", "rust-analyzer"]
+profile = "minimal"

sanitizers/suppressions/sanitizer-ignorelist.txt

@@ -29,7 +29,7 @@ src:test/beast/beast_PropertyStream_test.cpp
 src:src/test/app/Invariants_test.cpp
 
 # ASan false positive: stack-use-after-scope in ErrorCodes.h inline functions.
-# When Clang inlines the StaticString overloads (e.g. invalid_field_error(StaticString)),
+# When Clang inlines the StaticString overloads (e.g. invalidFieldError(StaticString)),
 # ASan scope-poisons the temporary std::string before the inlined callee finishes reading
 # through the const ref. This corrupts the coroutine stack and crashes the Simulate test.
 # See asan.supp comments for full explanation and planned fix.

src/benchmarks/libxrpl/CMakeLists.txt

@@ -0,0 +1,22 @@
+include(XrplAddBenchmark)
+
+# Benchmark requirements.
+find_package(benchmark REQUIRED)
+
+# Custom target for all benchmarks defined in this file.
+add_custom_target(xrpl.benchmarks)
+
+# Common library dependencies for every benchmark module. `benchmark_main`
+# supplies a `main()` that parses the standard Google Benchmark CLI flags
+# (`--benchmark_filter`, `--benchmark_format`, ...), so no per-module main.cpp
+# is needed.
+add_library(xrpl.imports.bench INTERFACE)
+target_link_libraries(
+    xrpl.imports.bench
+    INTERFACE benchmark::benchmark_main xrpl.libxrpl
+)
+
+# One benchmark executable for each module.
+xrpl_add_benchmark(nodestore)
+target_link_libraries(xrpl.bench.nodestore PRIVATE xrpl.imports.bench)
+add_dependencies(xrpl.benchmarks xrpl.bench.nodestore)

src/benchmarks/libxrpl/nodestore/Backend.cpp

@@ -0,0 +1,329 @@
+#include <xrpl/nodestore/Backend.h>
+
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/nodestore/NodeObject.h>
+#include <xrpl/nodestore/Types.h>
+
+#include <benchmark/benchmark.h>
+#include <benchmarks/libxrpl/nodestore/NodeStoreBench.h>
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace xrpl::NodeStore {
+namespace {
+
+constexpr std::size_t kPoolSizes[] = {1000, 10000, 100000};
+constexpr int kThreadCounts[] = {1, 4, 8};
+constexpr std::size_t kBatchSize = 256;
+
+constexpr std::string_view kNamePrefix = "BM_Backend_";
+constexpr std::string_view kNameSeparator = "/";
+
+struct RunState
+{
+    std::unique_ptr<BackendHarness> harness;
+    Batch present;                     // prefix-1 objects, eligible to be stored
+    Batch recent;                      // prefix-1 objects in the "future" key space
+    std::vector<uint256> missing;      // prefix-2 keys that are never stored
+    std::vector<std::size_t> shuffle;  // [0, poolSize) permutation for random-like access
+    std::size_t avgPayload = 0;        // mean getData().size() over `present`
+
+    void
+    release()
+    {
+        harness.reset();
+        Batch{}.swap(present);
+        Batch{}.swap(recent);
+        std::vector<uint256>{}.swap(missing);
+        std::vector<std::size_t>{}.swap(shuffle);
+    }
+};
+
+struct SetupContext
+{
+    RunState& rs;
+    Backend& backend;
+    std::size_t poolSize;
+};
+
+struct IterateContext
+{
+    RunState& rs;
+    Backend& backend;
+    std::size_t index;
+    std::size_t poolSize;
+};
+
+struct Workload
+{
+    std::string_view name;
+    std::function<void(SetupContext const&)> setup;
+    std::function<void(IterateContext const&)> iterate;
+    bool reportBytes = false;  // SetBytesProcessed from rs.avgPayload
+    bool clobber = true;       // ClobberMemory after the loop (false for pure stores)
+    bool pinToPool = false;    // pin iterations to one pool sweep instead of autotuning
+};
+
+// One store() per iteration. Iterations are pinned to one pool sweep (per
+// thread) so the index never wraps past the pool - otherwise NuDB::doInsert
+// swallows key_exists and the workload degenerates into duplicate-detection
+// no-ops.
+Workload const kInsert{
+    .name = "Insert",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.avgPayload = averagePayload(ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, backend, index, poolSize] = ctx;
+            backend.store(rs.present[index % poolSize]);
+        },
+    .reportBytes = true,
+    .clobber = false,
+    .pinToPool = true,
+};
+
+// One fetch() of a present key (a hit) per iteration.
+Workload const kFetch{
+    .name = "Fetch",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.avgPayload = averagePayload(ctx.rs.present);
+            prepopulate(ctx.backend, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, backend, index, poolSize] = ctx;
+            std::shared_ptr<NodeObject> result;
+            backend.fetch(rs.present[index % poolSize]->getHash(), &result);
+            benchmark::DoNotOptimize(result);
+        },
+    .reportBytes = true,
+};
+
+// One fetch() of a never-stored key (a miss); the backend is left empty.
+Workload const kMissing{
+    .name = "Missing",
+    .setup = [](SetupContext const& ctx) { ctx.rs.missing = makeMissingKeys(ctx.poolSize); },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, backend, index, poolSize] = ctx;
+            std::shared_ptr<NodeObject> result;
+            backend.fetch(rs.missing[index % poolSize], &result);
+            benchmark::DoNotOptimize(result);
+        },
+};
+
+// 80% hits / 20% misses. The fetch index comes from a shuffle table so access
+// is random-like without per-iteration RNG cost; sequential `index % poolSize`
+// would be artificially cache-friendly to RocksDB's block cache.
+Workload const kMixed{
+    .name = "Mixed",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.missing = makeMissingKeys(ctx.poolSize);
+            ctx.rs.shuffle = makeShuffle(ctx.poolSize, /*seed=*/1);
+            prepopulate(ctx.backend, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, backend, index, poolSize] = ctx;
+            std::shared_ptr<NodeObject> result;
+            auto const pick = rs.shuffle[index % poolSize];
+            if (index % 5 == 0)
+            {
+                backend.fetch(rs.missing[pick], &result);
+            }
+            else
+            {
+                backend.fetch(rs.present[pick]->getHash(), &result);
+            }
+            benchmark::DoNotOptimize(result);
+        },
+};
+
+// An xrpld-like cycle: a hit, a maybe-miss recent fetch, and a store. The
+// recent fetch uses the shuffle table (not `slot`) so it doesn't fetch the item
+// it's about to store this iteration - which would give an all-miss-then-hit
+// step instead of a smooth ramp. The store walks sequentially so each recent
+// object is stored once.
+Workload const kWork{
+    .name = "Work",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.recent = makePool(1, ctx.poolSize, ctx.poolSize);
+            ctx.rs.shuffle = makeShuffle(ctx.poolSize, /*seed=*/2);
+            prepopulate(ctx.backend, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, backend, index, poolSize] = ctx;
+            auto const slot = index % poolSize;
+            auto const pick = rs.shuffle[slot];
+
+            std::shared_ptr<NodeObject> historical;
+            backend.fetch(rs.present[pick]->getHash(), &historical);
+            benchmark::DoNotOptimize(historical);
+
+            std::shared_ptr<NodeObject> recent;
+            backend.fetch(rs.recent[pick]->getHash(), &recent);
+            benchmark::DoNotOptimize(recent);
+
+            backend.store(rs.recent[slot]);
+        },
+    .clobber = true,
+    .pinToPool = true,
+};
+
+auto
+makeRunner(Workload w, std::string cfg, std::shared_ptr<RunState> rs)
+{
+    return [w = std::move(w), cfg = std::move(cfg), rs = std::move(rs)](benchmark::State& state) {
+        auto const poolSize = static_cast<std::size_t>(state.range(0));
+        if (state.thread_index() == 0)
+        {
+            rs->harness = std::make_unique<BackendHarness>(cfg);
+            w.setup(
+                SetupContext{.rs = *rs, .backend = *rs->harness->backend, .poolSize = poolSize});
+        }
+
+        std::size_t index = state.thread_index();
+        for (auto _ : state)
+        {
+            w.iterate(
+                IterateContext{
+                    .rs = *rs,
+                    .backend = *rs->harness->backend,
+                    .index = index,
+                    .poolSize = poolSize});
+            index += state.threads();
+        }
+
+        if (w.clobber)
+            benchmark::ClobberMemory();
+
+        state.SetItemsProcessed(state.iterations());
+        if (w.reportBytes)
+            state.SetBytesProcessed(static_cast<std::int64_t>(state.iterations() * rs->avgPayload));
+
+        if (state.thread_index() == 0)
+            rs->release();
+    };
+}
+
+// Register workload `w` against backend `bc`, choosing the registration shape
+// from `w.pinToPool`.
+void
+registerWorkload(BackendConfig const& bc, Workload const& w)
+{
+    std::string const cfg = bc.config;
+    std::string name{kNamePrefix};
+    name += w.name;
+    name += kNameSeparator;
+    name += bc.name;
+
+    if (!w.pinToPool)
+    {
+        auto rs = std::make_shared<RunState>();
+        auto* b = benchmark::RegisterBenchmark(name, makeRunner(w, cfg, rs));
+        b->RangeMultiplier(10)->Range(kPoolSizes[0], kPoolSizes[std::size(kPoolSizes) - 1]);
+        b->Threads(1)->Threads(4)->Threads(8)->UseRealTime();
+
+        return;
+    }
+
+    for (auto const poolSize : kPoolSizes)
+    {
+        for (auto const threads : kThreadCounts)
+        {
+            if (poolSize % static_cast<std::size_t>(threads) != 0)
+                continue;
+
+            auto rs = std::make_shared<RunState>();
+            benchmark::RegisterBenchmark(name, makeRunner(w, cfg, rs))
+                ->Arg(poolSize)
+                ->Iterations(poolSize / static_cast<std::size_t>(threads))
+                ->Threads(threads)
+                ->UseRealTime();
+        }
+    }
+}
+
+// One storeBatch() of kBatchSize objects per iteration. Single-threaded:
+// Backend::storeBatch must not run concurrently with itself or store().
+// Iterations are pinned to the batch count so the index never wraps into
+// key_exists no-ops. Kept separate from Workload: batch slicing and the
+// per-batch item/byte accounting don't fit the thread-axis mold.
+void
+registerStoreBatch(BackendConfig const& bc)
+{
+    std::string const cfg = bc.config;
+    std::string name{kNamePrefix};
+    name += "StoreBatch";
+    name += kNameSeparator;
+    name += bc.name;
+    for (auto const poolSize : kPoolSizes)
+    {
+        auto const numBatches = poolSize / kBatchSize;
+        if (numBatches == 0)
+            continue;
+
+        auto rs = std::make_shared<RunState>();
+        benchmark::RegisterBenchmark(
+            name,
+            [rs, cfg](benchmark::State& state) {
+                auto const poolSize = static_cast<std::size_t>(state.range(0));
+                rs->harness = std::make_unique<BackendHarness>(cfg);
+                rs->present = makePool(1, poolSize);
+                rs->avgPayload = averagePayload(rs->present);
+                std::vector<Batch> const batches = sliceBatches(rs->present, kBatchSize);
+                if (batches.empty())
+                {
+                    state.SkipWithError("pool smaller than one batch");
+                    return;
+                }
+
+                std::size_t index = 0;
+                for (auto _ : state)
+                {
+                    rs->harness->backend->storeBatch(batches[index % batches.size()]);
+                    ++index;
+                }
+
+                state.SetItemsProcessed(static_cast<std::int64_t>(state.iterations() * kBatchSize));
+                state.SetBytesProcessed(
+                    static_cast<std::int64_t>(state.iterations() * kBatchSize * rs->avgPayload));
+                rs->release();
+            })
+            ->Arg(poolSize)
+            ->Iterations(numBatches);
+    }
+}
+
+[[maybe_unused]] bool const kRegistered = [] {
+    auto const workloads = std::to_array({&kInsert, &kFetch, &kMissing, &kMixed, &kWork});
+    for (auto const& bc : backendConfigs())
+    {
+        for (auto const* w : workloads)
+            registerWorkload(bc, *w);
+
+        registerStoreBatch(bc);
+    }
+    return true;
+}();
+
+}  // namespace
+}  // namespace xrpl::NodeStore

src/benchmarks/libxrpl/nodestore/Database.cpp

@@ -0,0 +1,243 @@
+#include <xrpl/nodestore/Database.h>
+
+#include <xrpl/basics/Blob.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/nodestore/NodeObject.h>
+#include <xrpl/nodestore/Types.h>
+
+#include <benchmark/benchmark.h>
+#include <benchmarks/libxrpl/nodestore/NodeStoreBench.h>
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace xrpl::NodeStore {
+namespace {
+
+// Number of distinct objects pre-generated per run.
+constexpr std::size_t kDefaultPoolSize = 100000;
+
+// Async read threads the Database spawns. Unused by the synchronous fetch path
+// these benchmarks take; kept fixed so runs are comparable.
+constexpr int kReadThreads = 4;
+
+constexpr std::string_view kNamePrefix = "BM_Database_";
+constexpr std::string_view kNameSeparator = "/";
+
+struct RunState
+{
+    std::unique_ptr<DatabaseHarness> harness;
+    Batch present;                     // prefix-1 objects, eligible to be stored
+    Batch recent;                      // prefix-1 objects in the "future" key space
+    std::vector<uint256> missing;      // prefix-2 keys that are never stored
+    std::vector<std::size_t> shuffle;  // [0, poolSize) permutation for random-like access
+    std::size_t avgPayload = 0;        // mean getData().size() over `present`
+};
+
+struct SetupContext
+{
+    RunState& rs;
+    Database& db;
+    std::size_t poolSize;
+};
+
+struct IterateContext
+{
+    RunState& rs;
+    Database& db;
+    std::uint32_t seq;
+    std::size_t index;
+    std::size_t poolSize;
+};
+
+struct Workload
+{
+    std::string_view name;
+    std::function<void(SetupContext const&)> setup;
+    std::function<void(IterateContext const&)> iterate;
+    bool reportBytes = false;
+    bool pinIterations = false;
+};
+
+void
+prepopulate(Database& db, Batch const& objects)
+{
+    auto const seq = db.earliestLedgerSeq();
+    for (auto const& obj : objects)
+    {
+        Blob data(obj->getData());
+        db.store(obj->getType(), std::move(data), obj->getHash(), seq);
+    }
+    db.sync();
+}
+
+// One store() per iteration; a fresh Blob copy is handed over each time.
+Workload const kStore{
+    .name = "Store",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.avgPayload = averagePayload(ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, db, seq, index, poolSize] = ctx;
+            auto const& obj = rs.present[index % poolSize];
+            Blob data(obj->getData());
+            db.store(obj->getType(), std::move(data), obj->getHash(), seq);
+        },
+    .reportBytes = true,
+    .pinIterations = true,
+};
+
+// One fetchNodeObject() of a stored key (a hit) per iteration.
+Workload const kFetch{
+    .name = "Fetch",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.avgPayload = averagePayload(ctx.rs.present);
+            prepopulate(ctx.db, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, db, seq, index, poolSize] = ctx;
+            auto obj = db.fetchNodeObject(rs.present[index % poolSize]->getHash(), seq);
+            benchmark::DoNotOptimize(obj);
+        },
+    .reportBytes = true,
+};
+
+// One fetchNodeObject() of a never-stored key (a miss) per iteration.
+Workload const kMissing{
+    .name = "Missing",
+    .setup = [](SetupContext const& ctx) { ctx.rs.missing = makeMissingKeys(ctx.poolSize); },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, db, seq, index, poolSize] = ctx;
+            auto obj = db.fetchNodeObject(rs.missing[index % poolSize], seq);
+            benchmark::DoNotOptimize(obj);
+        },
+};
+
+// 80% hits / 20% misses. The fetch index comes from a shuffle table so access
+// is random-like without per-iteration RNG cost; sequential `index % poolSize`
+// would be artificially cache-friendly.
+Workload const kMixed{
+    .name = "Mixed",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.missing = makeMissingKeys(ctx.poolSize);
+            ctx.rs.shuffle = makeShuffle(ctx.poolSize, /*seed=*/1);
+            prepopulate(ctx.db, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, db, seq, index, poolSize] = ctx;
+            auto const pick = rs.shuffle[index % poolSize];
+            std::shared_ptr<NodeObject> obj;
+            if (index % 5 == 0)
+            {
+                obj = db.fetchNodeObject(rs.missing[pick], seq);
+            }
+            else
+            {
+                obj = db.fetchNodeObject(rs.present[pick]->getHash(), seq);
+            }
+            benchmark::DoNotOptimize(obj);
+        },
+};
+
+// An xrpld-like cycle: a hit, a maybe-miss recent fetch, and a store. The
+// recent fetch uses the shuffle table (not `slot`) so it doesn't fetch the item
+// it's about to store this iteration - which would give an all-miss-then-hit
+// step instead of a smooth ramp. The store walks sequentially so each recent
+// object is stored once.
+Workload const kWork{
+    .name = "Work",
+    .setup =
+        [](SetupContext const& ctx) {
+            ctx.rs.present = makePool(1, ctx.poolSize);
+            ctx.rs.recent = makePool(1, ctx.poolSize, ctx.poolSize);
+            ctx.rs.shuffle = makeShuffle(ctx.poolSize, /*seed=*/2);
+            prepopulate(ctx.db, ctx.rs.present);
+        },
+    .iterate =
+        [](IterateContext const& ctx) {
+            auto& [rs, db, seq, index, poolSize] = ctx;
+            auto const slot = index % poolSize;
+            auto const pick = rs.shuffle[slot];
+
+            auto historical = db.fetchNodeObject(rs.present[pick]->getHash(), seq);
+            benchmark::DoNotOptimize(historical);
+
+            auto recent = db.fetchNodeObject(rs.recent[pick]->getHash(), seq);
+            benchmark::DoNotOptimize(recent);
+
+            auto const& obj = rs.recent[slot];
+            Blob data(obj->getData());
+            db.store(obj->getType(), std::move(data), obj->getHash(), seq);
+        },
+    .pinIterations = true,
+};
+
+void
+registerWorkload(BackendConfig const& bc, Workload const& w)
+{
+    auto rs = std::make_shared<RunState>();
+    std::string const cfg = bc.config;
+    std::string name{kNamePrefix};
+    name += w.name;
+    name += kNameSeparator;
+    name += bc.name;
+    auto* b = benchmark::RegisterBenchmark(name, [rs, cfg, w](benchmark::State& state) {
+        auto const poolSize = static_cast<std::size_t>(state.range(0));
+        rs->harness = std::make_unique<DatabaseHarness>(cfg, kReadThreads);
+        auto& db = *rs->harness->db;
+        w.setup(SetupContext{.rs = *rs, .db = db, .poolSize = poolSize});
+        auto const seq = db.earliestLedgerSeq();
+
+        std::size_t index = 0;
+        for (auto _ : state)
+        {
+            w.iterate(
+                IterateContext{
+                    .rs = *rs, .db = db, .seq = seq, .index = index, .poolSize = poolSize});
+            ++index;
+        }
+        benchmark::ClobberMemory();
+
+        state.SetItemsProcessed(state.iterations());
+        if (w.reportBytes)
+        {
+            state.SetBytesProcessed(static_cast<std::int64_t>(state.iterations() * rs->avgPayload));
+        }
+        rs->harness.reset();
+    });
+
+    b->Arg(kDefaultPoolSize);
+
+    if (w.pinIterations)
+        b->Iterations(kDefaultPoolSize);
+}
+
+[[maybe_unused]] bool const kRegistered = [] {
+    auto const workloads = std::to_array({&kStore, &kFetch, &kMissing, &kMixed, &kWork});
+    for (auto const& bc : backendConfigs())
+    {
+        for (auto const* w : workloads)
+            registerWorkload(bc, *w);
+    }
+    return true;
+}();
+
+}  // namespace
+}  // namespace xrpl::NodeStore

src/benchmarks/libxrpl/nodestore/NodeStoreBench.h

@@ -0,0 +1,318 @@
+#pragma once
+
+#include <xrpl/basics/Blob.h>
+#include <xrpl/basics/ByteUtilities.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/safe_cast.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/beast/utility/temp_dir.h>
+#include <xrpl/beast/xor_shift_engine.h>
+#include <xrpl/config/BasicConfig.h>
+#include <xrpl/nodestore/Backend.h>
+#include <xrpl/nodestore/Database.h>
+#include <xrpl/nodestore/DummyScheduler.h>
+#include <xrpl/nodestore/Manager.h>
+#include <xrpl/nodestore/NodeObject.h>
+#include <xrpl/nodestore/Scheduler.h>
+#include <xrpl/nodestore/Types.h>
+
+#include <boost/algorithm/string/classification.hpp>
+#include <boost/algorithm/string/split.hpp>
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <numeric>
+#include <random>
+#include <string>
+#include <utility>
+#include <vector>
+
+// Shared helpers for the NodeStore benchmarks.
+//
+namespace xrpl::NodeStore {
+
+// Fill `bytes` of memory at `buffer` with random bits drawn from `g`.
+template <class Generator>
+inline void
+rngcpy(void* buffer, std::size_t bytes, Generator& g)
+{
+    using result_type = typename Generator::result_type;
+    while (bytes >= sizeof(result_type))
+    {
+        auto const v = g();
+        std::memcpy(buffer, &v, sizeof(v));
+        buffer = reinterpret_cast<std::uint8_t*>(buffer) + sizeof(v);
+        bytes -= sizeof(v);
+    }
+
+    if (bytes > 0)
+    {
+        auto const v = g();
+        std::memcpy(buffer, &v, bytes);
+    }
+}
+
+/**
+ * @brief Deterministic generator of a reproducible sequence of random NodeObjects.
+ *
+ * Indexing is stable: `obj(n)` and `key(n)` always return the same value for a
+ * given `n`, regardless of call order, because the engine is reseeded from `n`
+ * on every call.
+ *
+ * Using different prefixes guarantees the two key spaces are disjoint for the fetch-miss
+ * workloads.
+ */
+class Sequence
+{
+private:
+    static constexpr auto kMinSize = 250;
+    static constexpr auto kMaxSize = 1250;
+
+    beast::xor_shift_engine gen_;
+    std::uint8_t prefix_;
+    std::discrete_distribution<std::uint32_t> dType_;
+    std::uniform_int_distribution<std::uint32_t> dSize_;
+
+public:
+    explicit Sequence(std::uint8_t prefix)
+        : prefix_(prefix)
+        // uniform distribution over hotLEDGER - hotTRANSACTION_NODE
+        // but exclude hotTRANSACTION = 2 (removed)
+        , dType_({1, 1, 0, 1, 1})
+        , dSize_(kMinSize, kMaxSize)
+    {
+    }
+
+    // Returns the n-th key. Used to generate keys that are never stored.
+    // The layout mirrors obj()'s: prefix at byte 0, RNG over the rest, so the
+    // two key spaces stay disjoint by construction (not by coincidence).
+    uint256
+    key(std::size_t n)
+    {
+        gen_.seed(n + 1);
+        uint256 result;
+        auto const data = static_cast<std::uint8_t*>(&*result.begin());
+        *data = prefix_;
+        rngcpy(data + 1, result.size() - 1, gen_);
+        return result;
+    }
+
+    // Returns the n-th complete NodeObject.
+    std::shared_ptr<NodeObject>
+    obj(std::size_t n)
+    {
+        gen_.seed(n + 1);
+        uint256 key;
+        auto const data = static_cast<std::uint8_t*>(&*key.begin());
+        *data = prefix_;
+        rngcpy(data + 1, key.size() - 1, gen_);
+        Blob value(dSize_(gen_));
+        rngcpy(&value[0], value.size(), gen_);
+        return NodeObject::createObject(
+            safeCast<NodeObjectType>(dType_(gen_)), std::move(value), key);
+    }
+
+    // Fills `b` with `size` consecutive NodeObjects starting at index `n`.
+    void
+    batch(std::size_t n, Batch& b, std::size_t size)
+    {
+        b.clear();
+        b.reserve(size);
+        while ((size--) != 0u)
+            b.push_back(obj(n++));
+    }
+};
+
+// Parse a comma-separated "key=value,key=value" string into a config Section.
+inline Section
+parseConfig(std::string const& s)
+{
+    Section section;
+    std::vector<std::string> values;
+    boost::split(values, s, boost::algorithm::is_any_of(","));
+    section.append(values);
+    return section;
+}
+
+// Pre-generate `count` distinct objects from key space `prefix`, starting at
+// sequence index `start`.
+inline Batch
+makePool(std::uint8_t prefix, std::size_t count, std::size_t start = 0)
+{
+    Sequence seq(prefix);
+    Batch pool;
+    pool.reserve(count);
+    for (std::size_t i = 0; i < count; ++i)
+        pool.push_back(seq.obj(start + i));
+    return pool;
+}
+
+// Pre-generate `count` keys disjoint from every `makePool(...)` object, for
+// measuring fetches that miss.
+inline std::vector<uint256>
+makeMissingKeys(std::size_t count)
+{
+    Sequence seq(2);
+    std::vector<uint256> keys;
+    keys.reserve(count);
+    for (std::size_t i = 0; i < count; ++i)
+        keys.push_back(seq.key(i));
+    return keys;
+}
+
+// Mean payload size across a pool, used for SetBytesProcessed throughput.
+inline std::size_t
+averagePayload(Batch const& pool)
+{
+    if (pool.empty())
+        return 0;
+    std::size_t total = 0;
+    for (auto const& obj : pool)
+        total += obj->getData().size();
+    return total / pool.size();
+}
+
+// Store every object and flush, so a following fetch exercises the real read
+// path rather than an in-memory write buffer.
+//
+// We chunk the write at kBatchWriteLimitSize because Types.h documents that as
+// the maximum allowed batch size. NuDB happens to tolerate larger batches
+// today, but the benchmark should not rely on that.
+//
+// sync() is a no-op for both NuDB and RocksDB at the moment (NuDB has a small
+// internal burst buffer that the timed loop will warm up). That is a contract
+// hint, not a guarantee; if either backend ever grows a real flush we get it
+// here for free.
+inline void
+prepopulate(Backend& backend, Batch const& objects)
+{
+    for (std::size_t i = 0; i < objects.size(); i += kBatchWriteLimitSize)
+    {
+        auto const end = std::min(i + kBatchWriteLimitSize, objects.size());
+        backend.storeBatch(Batch(objects.begin() + i, objects.begin() + end));
+    }
+    backend.sync();
+}
+
+// A deterministic permutation of [0, size). Lets the timed loop visit the
+// pre-generated pool in a random-like order with zero RNG cost per iteration -
+// the Timing_test workloads it replaces used uniform_int_distribution per
+// fetch, and a shuffle table reproduces that access pattern without paying for
+// the distribution inside the timed region.
+inline std::vector<std::size_t>
+makeShuffle(std::size_t size, std::uint64_t seed)
+{
+    std::vector<std::size_t> v(size);
+    std::iota(v.begin(), v.end(), std::size_t{0});
+    beast::xor_shift_engine gen(seed);
+    std::shuffle(v.begin(), v.end(), gen);
+    return v;
+}
+
+// Partition a pool into fixed-size batches. Any trailing remainder shorter than
+// `batchSize` is dropped, so every returned batch has exactly `batchSize`.
+inline std::vector<Batch>
+sliceBatches(Batch const& pool, std::size_t batchSize)
+{
+    std::vector<Batch> batches;
+    if (batchSize == 0)
+        return batches;
+    batches.reserve(pool.size() / batchSize);
+    for (std::size_t i = 0; i + batchSize <= pool.size(); i += batchSize)
+        batches.emplace_back(pool.begin() + i, pool.begin() + i + batchSize);
+    return batches;
+}
+
+/**
+ * @brief RAII owner of a NodeStore Backend opened on a private temporary directory.
+ *
+ * Member declaration order matters: `tempDir` is declared first so it is
+ * destroyed last, after the backend has closed and released its files.
+ */
+struct BackendHarness
+{
+    beast::TempDir tempDir;
+    DummyScheduler scheduler;
+    beast::Journal journal{beast::Journal::getNullSink()};
+    std::unique_ptr<Backend> backend;
+
+    explicit BackendHarness(std::string const& configString)
+    {
+        Section config = parseConfig(configString);
+        // A private, unique path per harness, so concurrent or repeated runs
+        // never share on-disk state.
+        config.set("path", tempDir.path());
+        backend =
+            Manager::instance().makeBackend(config, megabytes(std::size_t{4}), scheduler, journal);
+        backend->setDeletePath();
+        backend->open();
+    }
+
+    ~BackendHarness()
+    {
+        if (backend)
+            backend->close();
+    }
+};
+
+/**
+ * RAII owner of a NodeStore Database - the application-facing wrapper around a
+ * Backend, which adds fetch/store accounting and the async read-thread pool.
+ */
+struct DatabaseHarness
+{
+    beast::TempDir tempDir;
+    DummyScheduler scheduler;
+    beast::Journal journal{beast::Journal::getNullSink()};
+    std::unique_ptr<Database> db;
+
+    DatabaseHarness(std::string const& configString, int readThreads)
+    {
+        Section config = parseConfig(configString);
+        config.set("path", tempDir.path());
+        db = Manager::instance().makeDatabase(
+            megabytes(std::size_t{4}), scheduler, readThreads, config, journal);
+    }
+
+    ~DatabaseHarness()
+    {
+        if (db)
+            db->stop();
+    }
+};
+
+// A NodeStore backend to benchmark, named for the --benchmark_filter CLI flag.
+struct BackendConfig
+{
+    char const* name;    // short label, e.g. "nudb"
+    char const* config;  // parseConfig() string, e.g. "type=nudb"
+};
+
+// The backends every workload is registered against.
+//
+// The in-memory backend is intentionally excluded. It keeps its table in a
+// process-global map keyed by path, with no removal API, so building a fresh
+// backend per run - as a microbenchmark must - would leak the whole dataset on
+// every run. Timing_test, the suite this benchmark replaces, excluded it for
+// the same reason. NuDB and RocksDB are the production backends worth timing.
+//
+// RocksDB is included only when it was compiled in (xrpl.libxrpl carries
+// XRPL_ROCKSDB_AVAILABLE transitively).
+inline std::vector<BackendConfig> const&
+backendConfigs()
+{
+    static std::vector<BackendConfig> const kConfigs = {
+        {.name = "nudb", .config = "type=nudb"},
+#if XRPL_ROCKSDB_AVAILABLE
+        {.name = "rocksdb",
+         .config = "type=rocksdb,open_files=2000,filter_bits=12,cache_mb=256,"
+                   "file_size_mb=8,file_size_mult=2"},
+#endif
+    };
+    return kConfigs;
+}
+
+}  // namespace xrpl::NodeStore

src/libxrpl/basics/Number.cpp

@@ -277,6 +277,25 @@ public:
     void
     doDropDigit(T& mantissa, int& exponent) noexcept;
 
+    // Modify the result to the correctly rounded value
+    template <UnsignedMantissa T>
+    void
+    doRoundUp(bool& negative, T& mantissa, int& exponent, std::string location);
+
+    // Modify the result to the correctly rounded value
+    template <UnsignedMantissa T>
+    void
+    doRoundDown(bool& negative, T& mantissa, int& exponent) const;
+
+    // Modify the result to the correctly rounded value
+    void
+    doRound(rep& drops, std::string location) const;
+
+private:
+    template <UnsignedMantissa T>
+    void
+    pushOverflow(T mantissa);
+
     enum class Round {
         // The result is exact. No rounding is needed. Only used if cuspRoundingFix is Enabled330 or
         // higher.
@@ -289,37 +308,22 @@ public:
         // The result was exactly half-way between two integers. This will round to even.
         Even = 0,
         // Round up. Always adds 1 (or subtracts 1 in some cases if cuspRoundingFix is not
-        // Enabled)
+        // Enabled330)
         Up = 1,
     };
 
-    // Indicate round direction:  1 is up, -1 is down, 0 is even
+    // Indicate round direction. See Round enum above.
     // This enables the client to round towards nearest, and on
     // tie, round towards even.
     [[nodiscard]] Round
     round() const noexcept;
 
-    // Modify the result to the correctly rounded value
-    template <UnsignedMantissa T>
-    void
-    doRoundUp(bool& negative, T& mantissa, int& exponent, std::string location);
-
-    // Modify the result to the correctly rounded value
-    template <UnsignedMantissa T>
-    void
-    doRoundDown(bool& negative, T& mantissa, int& exponent);
-
-    // Modify the result to the correctly rounded value
-    void
-    doRound(rep& drops, std::string location) const;
-
-private:
     void
     doPush(unsigned d) noexcept;
 
     template <UnsignedMantissa T>
     void
-    bringIntoRange(bool& negative, T& mantissa, int& exponent);
+    bringIntoRange(bool& negative, T& mantissa, int& exponent) const;
 };
 
 inline void
@@ -349,6 +353,7 @@ Number::Guard::isNegative() const noexcept
 inline void
 Number::Guard::doPush(unsigned d) noexcept
 {
+    XRPL_ASSERT(d < 10, "xrpl::Number::Guard::doPush : valid digit");
     xbit_ = xbit_ || ((digits_ & 0x0000'0000'0000'000F) != 0);
     digits_ >>= 4;
     digits_ |= (d & 0x0000'0000'0000'000FULL) << 60;
@@ -396,10 +401,69 @@ Number::Guard::doDropDigit<uint128_t>(uint128_t& mantissa, int& exponent) noexce
     ++exponent;
 }
 
+template <UnsignedMantissa T>
+void
+Number::Guard::pushOverflow(T mantissa)
+{
+    XRPL_ASSERT(mantissa <= kMaxRepUp, "xrpl::Number::Guard::pushOverflow : valid mantissa");
+    if (cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 && mantissa >= kMaxRep &&
+        mantissa < kMaxRepUp)
+    {
+        // Special case rounding rules for the values in the range [kMaxRep, kMaxRepUp).
+
+        auto constexpr spread = kMaxRepUp - kMaxRep;
+        static_assert(spread == 3);
+
+        // Round in two steps.
+
+        // The first step uses the digits _already_ in the Guard to possibly round the mantissa up.
+        // Ultimately, the purpose of this step is to capture rounding where the stored digits would
+        // change the decision without those digits. (e.g. From just _below_ the midpoint to just
+        // _above_ the midpoint for ToNearest, or from kMaxRep into the in-between for Upward. Make
+        // an exception if the final digit is 9, because it can only get larger, and we don't want
+        // to bump up to kMaxRepUp.
+        if (mantissa % 10 < 9)
+        {
+            // Intentionally use integer math to get the largest value under the midpoint.
+            auto constexpr kMidpoint = kMaxRep + (spread / 2);
+            static_assert(kMidpoint == kMaxRep + 1);
+            auto const r = round();
+            if (r == Round::Up || (r == Round::Even && mantissa == kMidpoint))
+            {
+                ++mantissa;
+            }
+        }
+
+        // The second step scales the final digit of the updated mantissa proportionally, converting
+        // from (kMaxRep, kMaxRepUp) to (0 to 9]. It then pushes that scaled digit onto the guard as
+        // if it was a digit that got removed, but doesn't actually remove it. This method should be
+        // future-proof in case the number of mantissa bits ever changes. (Though for integer values
+        // of the form 2^(2^x-1), the spread will always be the same.) Effects:
+        // * For round to nearest
+        //      * if the updated mantissa is below the midpoint, it'll round "down" to kMaxRep
+        //      * if above the midpoint, it'll round "up" to kMaxRepUp
+        //      * it can never be exactly at the midpoint, because kMaxRepUp is always even, and
+        //        kMaxRep is always odd, so don't worry about that case.
+        // * For round upward, will round up to kMaxRepUp for positive values, down to kMaxRep for
+        //   negative.
+        // * For round downward, does the opposite of upward.
+        // * For round toward zero, always rounds down to kMaxRep.
+
+        auto const diff = mantissa - kMaxRep;
+        auto const digit = static_cast<unsigned>((diff * 10) / spread);
+        XRPL_ASSERT(
+            digit < 10u && digit != 5, "xrpl::Number::Guard::pushOverflow : valid overflow digit");
+
+        // Don't remove the digit from the mantissa, but add it to the guard as if it was.
+        push(digit);
+    }
+}
+
 // Returns:
-//     -1 if Guard is less than half
-//      0 if Guard is exactly half
-//      1 if Guard is greater than half
+//     Exact if Guard is _zero_, and appropriate amendments are enabled
+//     Down  if Guard is less than half
+//     Even  if Guard is exactly half
+//     Up    if Guard is greater than half
 Number::Guard::Round
 Number::Guard::round() const noexcept
 {
@@ -445,17 +509,23 @@ Number::Guard::round() const noexcept
 
 template <UnsignedMantissa T>
 void
-Number::Guard::bringIntoRange(bool& negative, T& mantissa, int& exponent)
+Number::Guard::bringIntoRange(bool& negative, T& mantissa, int& exponent) const
 {
     // Bring mantissa back into the minMantissa / maxMantissa range AFTER
-    // rounding
-    if (mantissa < minMantissa)
+    // rounding.
+    if (mantissa < minMantissa &&
+        (cuspRoundingFix < MantissaRange::CuspRoundingFix::Enabled330 || mantissa != 0))
     {
         mantissa *= 10;
         --exponent;
     }
-    if (exponent < kMinExponent)
+    // mantissa should never be 0, but if it _is_ assert, but fall back to making the result kZero.
+    if (exponent < kMinExponent ||
+        (cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 && mantissa == 0))
     {
+        // Engineers: If you hit this assert, you probably did something wrong in the operation
+        // leading up to the rounding work.
+        XRPL_ASSERT(mantissa != 0, "xrpl::Number::Guard::bringIntoRange : valid mantissa");
         static constexpr Number kZero = Number{};
 
         negative = kZero.negative_;
@@ -468,7 +538,9 @@ template <UnsignedMantissa T>
 void
 Number::Guard::doRoundUp(bool& negative, T& mantissa, int& exponent, std::string location)
 {
-    auto r = round();
+    pushOverflow(mantissa);
+
+    auto const r = round();
     if (r == Round::Up || (r == Round::Even && (mantissa & 1) == 1))
     {
         auto const safeToIncrement = [this](auto const& mantissa) {
@@ -485,18 +557,29 @@ Number::Guard::doRoundUp(bool& negative, T& mantissa, int& exponent, std::string
             }
             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
-                // chance 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, location);
-                return;
+                if (cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 &&
+                    mantissa > kMaxRep && mantissa < kMaxRepUp)
+                {
+                    // When rounding up a value in between kMaxRep, and kMaxRepUp, round to
+                    // kMaxRepUp. Note that the decision for this rounding is dominated by the
+                    // results of pushOverflow.
+                    mantissa = kMaxRepUp;
+                }
+                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 chance 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, location);
+                    return;
+                }
             }
         }
         else
@@ -514,6 +597,14 @@ Number::Guard::doRoundUp(bool& negative, T& mantissa, int& exponent, std::string
             }
         }
     }
+    else if (
+        cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 && mantissa > kMaxRep &&
+        mantissa < kMaxRepUp)
+    {
+        // When rounding down a value in between kMaxRep, and kMaxRepUp, round to kMaxRep.
+        // Note that the decision for this rounding is dominated by the results of pushOverflow.
+        mantissa = kMaxRep;
+    }
     bringIntoRange(negative, mantissa, exponent);
     if (exponent > kMaxExponent)
         Throw<std::overflow_error>(std::string(location));
@@ -521,8 +612,10 @@ Number::Guard::doRoundUp(bool& negative, T& mantissa, int& exponent, std::string
 
 template <UnsignedMantissa T>
 void
-Number::Guard::doRoundDown(bool& negative, T& mantissa, int& exponent)
+Number::Guard::doRoundDown(bool& negative, T& mantissa, int& exponent) const
 {
+    // Do not pushOverflow here.
+
     auto r = round();
     if (cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330)
     {
@@ -557,6 +650,8 @@ Number::Guard::doRoundDown(bool& negative, T& mantissa, int& exponent)
 void
 Number::Guard::doRound(rep& drops, std::string location) const
 {
+    // Do not pushOverflow here.
+
     auto r = round();
     if (r == Round::Up || (r == Round::Even && (drops & 1) == 1))
     {
@@ -573,6 +668,8 @@ Number::Guard::doRound(rep& drops, std::string location) const
         }
         ++drops;
     }
+    XRPL_ASSERT(drops >= 0, "xrpl::Number::Guard::doRound : positive magnitude");
+
     if (isNegative())
         drops = -drops;
 }
@@ -622,7 +719,9 @@ doNormalize(
 {
     static constexpr auto kMinExponent = Number::kMinExponent;
     static constexpr auto kMaxExponent = Number::kMaxExponent;
-    static constexpr auto kMaxRep = Number::kMaxRep;
+    auto const repLimit = cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330
+        ? Number::kMaxRepUp
+        : Number::kMaxRep;
 
     using Guard = Number::Guard;
 
@@ -672,17 +771,17 @@ doNormalize(
     //      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.
-    if (m > kMaxRep)
+    if (m > repLimit)
     {
         if (exponent >= kMaxExponent)
             throw std::overflow_error("Number::normalize 1.5");
         g.doDropDigit(m, exponent);
     }
     // Before modification, m should be within the min/max range. After
-    // 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");
+    // modification, it must be less than repLimit. In other words, the original
+    // value should have been no more than repLimit * 10.
+    // (repLimit * 10 > maxMantissa)
+    XRPL_ASSERT_PARTS(m <= repLimit, "xrpl::doNormalize", "intermediate mantissa fits in limit");
     mantissa = m;
 
     g.doRoundUp(negative, mantissa, exponent, "Number::normalize 2");
@@ -814,6 +913,9 @@ Number::operator+=(Number const& y)
     auto const& maxMantissa = g.maxMantissa;
     auto const cuspRoundingFix = g.cuspRoundingFix;
 
+    auto const repLimit =
+        cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 ? kMaxRepUp : kMaxRep;
+
     // Bring the exponents of both values into agreement, so the mantissas are on the same scale
     //   and can be added directly together.
 
@@ -898,7 +1000,7 @@ Number::operator+=(Number const& y)
         }
         else
         {
-            if (xm > maxMantissa || xm > kMaxRep)
+            if (xm > maxMantissa || xm > repLimit)
             {
                 g.doDropDigit(xm, xe);
             }
@@ -942,7 +1044,7 @@ Number::operator+=(Number const& y)
         {
             // Grow xm/xe and pull digits out of the Guard until it's back in the
             // minMantissa/maxMantissa range.
-            while (xm < minMantissa && xm * 10 <= kMaxRep)
+            while (xm < minMantissa && xm * 10 <= repLimit)
             {
                 xm *= 10;
                 xm -= g.pop();
@@ -1016,8 +1118,10 @@ Number::operator*=(Number const& y)
         g.setNegative();
 
     auto const& maxMantissa = g.maxMantissa;
+    auto const repLimit =
+        g.cuspRoundingFix >= MantissaRange::CuspRoundingFix::Enabled330 ? kMaxRepUp : kMaxRep;
 
-    while (zm > maxMantissa || zm > kMaxRep)
+    while (zm > maxMantissa || zm > repLimit)
     {
         g.doDropDigit(zm, ze);
     }
@@ -1282,8 +1386,11 @@ to_string(Number const& amount)
         }
         std::string ret = negative ? "-" : "";
         ret.append(std::to_string(mantissa));
-        ret.append(1, 'e');
-        ret.append(std::to_string(exponent));
+        if (exponent != 0)
+        {
+            ret.append(1, 'e');
+            ret.append(std::to_string(exponent));
+        }
         return ret;
     }
 

src/libxrpl/core/detail/Workers.cpp

@@ -127,15 +127,11 @@ Workers::deleteWorkers(beast::LockFreeStack<Worker>& stack)
     {
         Worker const* const worker = stack.popFront();
 
-        if (worker != nullptr)
-        {
-            // This call blocks until the thread orderly exits
-            delete worker;
-        }
-        else
-        {
+        if (worker == nullptr)
             break;
-        }
+
+        // This call blocks until the thread orderly exits
+        delete worker;
     }
 }
 

src/libxrpl/json/json_value.cpp

@@ -314,8 +314,7 @@ Value::~Value()
 
         case ValueType::Array:
         case ValueType::Object:
-            if (value_.mapVal != nullptr)
-                delete value_.mapVal;
+            delete value_.mapVal;
             break;
 
         // LCOV_EXCL_START

src/libxrpl/ledger/helpers/LendingHelpers.cpp

@@ -312,6 +312,25 @@ computeInterestAndFeeParts(
     return std::make_pair(interest - fee, fee);
 }
 
+/* Rounds a raw (unrounded) interest amount to the loan's scale, then splits
+ * the rounded amount into net interest (to the vault) and management fee (to
+ * the broker).
+ *
+ * This is the common "round then split" step shared by late payment, full
+ * payment, and overpayment interest calculations.
+ */
+std::pair<Number, Number>
+roundAndSplitInterest(
+    Asset const& asset,
+    Number const& rawInterest,
+    TenthBips16 managementFeeRate,
+    std::int32_t loanScale,
+    Number::RoundingMode mode = Number::getround())
+{
+    auto const interest = roundToAsset(asset, rawInterest, loanScale, mode);
+    return computeInterestAndFeeParts(asset, interest, managementFeeRate, loanScale);
+}
+
 /* Calculates penalty interest accrued on overdue payments.
  * Returns 0 if payment is not late.
  *
@@ -387,22 +406,18 @@ loanAccruedInterest(
  *
  * This is the core function that updates the Loan ledger object fields based on
  * a computed payment.
-
- * The function is templated to work with both direct Number/uint32_t values
- * (for testing/simulation) and ValueProxy types (for actual ledger updates).
  */
-template <class NumberProxy, class UInt32Proxy, class UInt32OptionalProxy>
 LoanPaymentParts
-doPayment(
-    ExtendedPaymentComponents const& payment,
-    NumberProxy& totalValueOutstandingProxy,
-    NumberProxy& principalOutstandingProxy,
-    NumberProxy& managementFeeOutstandingProxy,
-    UInt32Proxy& paymentRemainingProxy,
-    UInt32Proxy& prevPaymentDateProxy,
-    UInt32OptionalProxy& nextDueDateProxy,
-    std::uint32_t paymentInterval)
+doPayment(ExtendedPaymentComponents const& payment, SLE::ref loan)
 {
+    auto totalValueOutstandingProxy = loan->at(sfTotalValueOutstanding);
+    auto principalOutstandingProxy = loan->at(sfPrincipalOutstanding);
+    auto managementFeeOutstandingProxy = loan->at(sfManagementFeeOutstanding);
+    auto paymentRemainingProxy = loan->at(sfPaymentRemaining);
+    auto prevPaymentDateProxy = loan->at(sfPreviousPaymentDueDate);
+    auto nextDueDateProxy = loan->at(sfNextPaymentDueDate);
+    std::uint32_t const paymentInterval = loan->at(sfPaymentInterval);
+
     XRPL_ASSERT_PARTS(nextDueDateProxy, "xrpl::detail::doPayment", "Next due date proxy set");
 
     if (payment.specialCase == PaymentSpecialCase::Final)
@@ -470,16 +485,12 @@ doPayment(
 
     // Principal can never exceed total value (principal is part of total value)
     XRPL_ASSERT_PARTS(
-        // Use an explicit cast because the template parameter can be
-        // ValueProxy<Number> or Number
         static_cast<Number>(principalOutstandingProxy) <=
             static_cast<Number>(totalValueOutstandingProxy),
         "xrpl::detail::doPayment",
         "principal does not exceed total");
 
     XRPL_ASSERT_PARTS(
-        // Use an explicit cast because the template parameter can be
-        // ValueProxy<Number> or Number
         static_cast<Number>(managementFeeOutstandingProxy) >= beast::kZero,
         "xrpl::detail::doPayment",
         "fee outstanding stays valid");
@@ -717,22 +728,23 @@ tryOverpayment(
  * overpayment would leave the loan in an invalid state, we can reject it
  * gracefully without corrupting the ledger data.
  */
-template <class NumberProxy>
 std::expected<LoanPaymentParts, TER>
 doOverpayment(
     Rules const& rules,
     Asset const& asset,
     std::int32_t loanScale,
     ExtendedPaymentComponents const& overpaymentComponents,
-    NumberProxy& totalValueOutstandingProxy,
-    NumberProxy& principalOutstandingProxy,
-    NumberProxy& managementFeeOutstandingProxy,
-    NumberProxy& periodicPaymentProxy,
+    SLE::ref loan,
     Number const& periodicRate,
-    std::uint32_t const paymentRemaining,
     TenthBips16 const managementFeeRate,
     beast::Journal j)
 {
+    auto totalValueOutstandingProxy = loan->at(sfTotalValueOutstanding);
+    auto principalOutstandingProxy = loan->at(sfPrincipalOutstanding);
+    auto managementFeeOutstandingProxy = loan->at(sfManagementFeeOutstanding);
+    auto periodicPaymentProxy = loan->at(sfPeriodicPayment);
+    auto const paymentsRemaining = loan->at(sfPaymentRemaining);
+
     auto const loanState = constructLoanState(
         totalValueOutstandingProxy, principalOutstandingProxy, managementFeeOutstandingProxy);
     auto const periodicPayment = periodicPaymentProxy;
@@ -744,7 +756,7 @@ doOverpayment(
                     << ", interestPart: " << overpaymentComponents.trackedInterestPart()
                     << ", untrackedInterest: " << overpaymentComponents.untrackedInterest
                     << ", totalDue: " << overpaymentComponents.totalDue
-                    << ", payments remaining :" << paymentRemaining;
+                    << ", payments remaining :" << paymentsRemaining;
 
     // Attempt to re-amortize the loan with the overpayment applied.
     // This modifies the temporary copies, leaving the proxies unchanged.
@@ -756,7 +768,7 @@ doOverpayment(
         loanState,
         periodicPayment,
         periodicRate,
-        paymentRemaining,
+        paymentsRemaining,
         managementFeeRate,
         j);
     if (!ret)
@@ -864,16 +876,15 @@ std::expected<ExtendedPaymentComponents, TER>
 computeLatePayment(
     Asset const& asset,
     ApplyView const& view,
-    Number const& principalOutstanding,
-    std::int32_t nextDueDate,
+    SLE::const_ref loan,
     ExtendedPaymentComponents const& periodic,
-    TenthBips32 lateInterestRate,
-    std::int32_t loanScale,
-    Number const& latePaymentFee,
     STAmount const& amount,
     TenthBips16 managementFeeRate,
     beast::Journal j)
 {
+    std::int32_t const nextDueDate = loan->at(sfNextPaymentDueDate);
+    std::int32_t const loanScale = loan->at(sfLoanScale);
+
     // Check if the due date has passed. If not, reject the payment as
     // being too soon
     if (!hasExpired(view, nextDueDate))
@@ -881,15 +892,15 @@ computeLatePayment(
 
     // Calculate the penalty interest based on how long the payment is overdue.
     auto const latePaymentInterest = loanLatePaymentInterest(
-        principalOutstanding, lateInterestRate, view.parentCloseTime(), nextDueDate);
+        loan->at(sfPrincipalOutstanding),
+        TenthBips32{loan->at(sfLateInterestRate)},
+        view.parentCloseTime(),
+        nextDueDate);
 
     // Round the late interest and split it between the vault (net interest)
-    // and the broker (management fee portion). This lambda ensures we
-    // round before splitting to maintain precision.
-    auto const [roundedLateInterest, roundedLateManagementFee] = [&]() {
-        auto const interest = roundToAsset(asset, latePaymentInterest, loanScale);
-        return computeInterestAndFeeParts(asset, interest, managementFeeRate, loanScale);
-    }();
+    // and the broker (management fee portion).
+    auto const [roundedLateInterest, roundedLateManagementFee] =
+        roundAndSplitInterest(asset, latePaymentInterest, managementFeeRate, loanScale);
 
     XRPL_ASSERT(roundedLateInterest >= 0, "xrpl::detail::computeLatePayment : valid late interest");
     XRPL_ASSERT_PARTS(
@@ -908,7 +919,7 @@ computeLatePayment(
         // 1. Regular service fee (from periodic.untrackedManagementFee)
         // 2. Late payment fee (fixed penalty)
         // 3. Management fee portion of late interest
-        periodic.untrackedManagementFee + latePaymentFee + roundedLateManagementFee,
+        periodic.untrackedManagementFee + loan->at(sfLatePaymentFee) + roundedLateManagementFee,
 
         // Untracked interest includes:
         // 1. Any untracked interest from the regular payment (usually 0)
@@ -958,22 +969,15 @@ std::expected<ExtendedPaymentComponents, TER>
 computeFullPayment(
     Asset const& asset,
     ApplyView& view,
-    Number const& principalOutstanding,
-    Number const& managementFeeOutstanding,
-    Number const& periodicPayment,
-    std::uint32_t paymentRemaining,
-    std::uint32_t prevPaymentDate,
-    std::uint32_t const startDate,
-    std::uint32_t const paymentInterval,
-    TenthBips32 const closeInterestRate,
-    std::int32_t loanScale,
-    Number const& totalInterestOutstanding,
+    SLE::const_ref loan,
     Number const& periodicRate,
-    Number const& closePaymentFee,
     STAmount const& amount,
     TenthBips16 managementFeeRate,
     beast::Journal j)
 {
+    std::uint32_t const paymentRemaining = loan->at(sfPaymentRemaining);
+    std::int32_t const loanScale = loan->at(sfLoanScale);
+
     // Full payment must be made before the final scheduled payment.
     if (paymentRemaining <= 1)
     {
@@ -986,7 +990,7 @@ computeFullPayment(
     // This theoretical (unrounded) value is used to compute interest and
     // penalties accurately.
     Number const theoreticalPrincipalOutstanding = loanPrincipalFromPeriodicPayment(
-        view.rules(), periodicPayment, periodicRate, paymentRemaining);
+        view.rules(), loan->at(sfPeriodicPayment), periodicRate, paymentRemaining);
 
     // Full payment interest includes both accrued interest (time since last
     // payment) and prepayment penalty (for closing early).
@@ -994,18 +998,21 @@ computeFullPayment(
         theoreticalPrincipalOutstanding,
         periodicRate,
         view.parentCloseTime(),
-        paymentInterval,
-        prevPaymentDate,
-        startDate,
-        closeInterestRate);
+        loan->at(sfPaymentInterval),
+        loan->at(sfPreviousPaymentDueDate),
+        loan->at(sfStartDate),
+        TenthBips32{loan->at(sfCloseInterestRate)});
 
-    // Split the full payment interest into net interest (to vault) and
-    // management fee (to broker), applying proper rounding.
-    auto const [roundedFullInterest, roundedFullManagementFee] = [&]() {
-        auto const interest =
-            roundToAsset(asset, fullPaymentInterest, loanScale, Number::RoundingMode::Downward);
-        return computeInterestAndFeeParts(asset, interest, managementFeeRate, loanScale);
-    }();
+    // Split the full payment interest into net interest (to vault) and management fee (to broker),
+    // applying proper rounding.
+    auto const [roundedFullInterest, roundedFullManagementFee] = roundAndSplitInterest(
+        asset, fullPaymentInterest, managementFeeRate, loanScale, Number::RoundingMode::Downward);
+
+    LoanState const loanState = constructLoanState(loan);
+    Number const principalOutstanding = loanState.principalOutstanding;
+    Number const managementFeeOutstanding = loanState.managementFeeDue;
+    Number const totalInterestOutstanding = loanState.interestDue;
+    Number const closePaymentFee = roundToAsset(asset, loan->at(sfClosePaymentFee), loanScale);
 
     ExtendedPaymentComponents const full{
         PaymentComponents{
@@ -1046,8 +1053,7 @@ computeFullPayment(
         "xrpl::detail::computeFullPayment",
         "total due is rounded");
 
-    JLOG(j.trace()) << "computeFullPayment result: periodicPayment: " << periodicPayment
-                    << ", periodicRate: " << periodicRate
+    JLOG(j.trace()) << "computeFullPayment result: periodicRate: " << periodicRate
                     << ", paymentRemaining: " << paymentRemaining
                     << ", theoreticalPrincipalOutstanding: " << theoreticalPrincipalOutstanding
                     << ", fullPaymentInterest: " << fullPaymentInterest
@@ -1298,6 +1304,34 @@ computePaymentComponents(
     };
 }
 
+/* Thin overload of computePaymentComponents() that unwraps the tracked
+ * fields directly from the Loan ledger object. `periodicRate` is derived
+ * rather than stored, and `managementFeeRate` comes from the LoanBroker, not
+ * the Loan, so both remain explicit parameters. Kept separate from the
+ * value-based overload above, which is exercised directly by unit tests
+ * against simulated (non-ledger) loan states.
+ */
+PaymentComponents
+computePaymentComponents(
+    Rules const& rules,
+    Asset const& asset,
+    SLE::ref loan,
+    Number const& periodicRate,
+    TenthBips16 managementFeeRate)
+{
+    return computePaymentComponents(
+        rules,
+        asset,
+        loan->at(sfLoanScale),
+        loan->at(sfTotalValueOutstanding),
+        loan->at(sfPrincipalOutstanding),
+        loan->at(sfManagementFeeOutstanding),
+        loan->at(sfPeriodicPayment),
+        periodicRate,
+        loan->at(sfPaymentRemaining),
+        managementFeeRate);
+}
+
 /* Computes payment components for an overpayment scenario.
  *
  * An overpayment occurs when a borrower pays more than the scheduled periodic
@@ -1342,11 +1376,12 @@ computeOverpaymentComponents(
     // This interest doesn't follow the normal amortization schedule - it's
     // a one-time charge for paying early.
     // Equation (20) and (21) from XLS-66 spec, Section A-2 Equation Glossary
-    auto const [roundedOverpaymentInterest, roundedOverpaymentManagementFee] = [&]() {
-        auto const interest =
-            roundToAsset(asset, tenthBipsOfValue(overpayment, overpaymentInterestRate), loanScale);
-        return detail::computeInterestAndFeeParts(asset, interest, managementFeeRate, loanScale);
-    }();
+    auto const [roundedOverpaymentInterest, roundedOverpaymentManagementFee] =
+        roundAndSplitInterest(
+            asset,
+            tenthBipsOfValue(overpayment, overpaymentInterestRate),
+            managementFeeRate,
+            loanScale);
 
     auto const result = detail::ExtendedPaymentComponents{
         // Build the payment components, after fees and penalty
@@ -1373,6 +1408,265 @@ computeOverpaymentComponents(
     return result;
 }
 
+/* Derives the two rate values every make*Payment() helper needs: the
+ * broker's management fee rate, and the loan's periodic (per-payment-period)
+ * interest rate.
+ */
+std::pair<TenthBips16, Number>
+loanRatesFor(SLE::const_ref loan, SLE::const_ref brokerSle)
+{
+    TenthBips16 const managementFeeRate{brokerSle->at(sfManagementFeeRate)};
+    TenthBips32 const interestRate{loan->at(sfInterestRate)};
+    Number const periodicRate = loanPeriodicRate(interestRate, loan->at(sfPaymentInterval));
+    XRPL_ASSERT(interestRate == 0 || periodicRate > 0, "xrpl::detail::loanRatesFor : valid rate");
+    return {managementFeeRate, periodicRate};
+}
+
+/* Handles a full (early payoff) payment. Implements the "full payment"
+ * branch of the make_payment function from the XLS-66 spec, Section
+ * 3.2.4.4.
+ */
+std::expected<LoanPaymentParts, TER>
+makeFullPayment(
+    Asset const& asset,
+    ApplyView& view,
+    SLE::ref loan,
+    SLE::const_ref brokerSle,
+    STAmount const& amount,
+    beast::Journal j)
+{
+    auto const [managementFeeRate, periodicRate] = loanRatesFor(loan, brokerSle);
+
+    auto const fullPaymentComponents =
+        computeFullPayment(asset, view, loan, periodicRate, amount, managementFeeRate, j);
+
+    // computeFullPayment only ever fails with a genuine error TER (never
+    // tesSUCCESS), so there is no separate "no-op" outcome to handle here.
+    if (fullPaymentComponents.has_value())
+        return doPayment(*fullPaymentComponents, loan);
+    return std::unexpected(fullPaymentComponents.error());
+}
+
+/* Handles a late payment (past due date, with the late-payment flag set).
+ * Implements the "late payment" branch of the make_payment function from
+ * the XLS-66 spec, Section 3.2.4.4.
+ */
+std::expected<LoanPaymentParts, TER>
+makeLatePayment(
+    Asset const& asset,
+    ApplyView const& view,
+    SLE::ref loan,
+    SLE::const_ref brokerSle,
+    STAmount const& amount,
+    beast::Journal j)
+{
+    auto const [managementFeeRate, periodicRate] = loanRatesFor(loan, brokerSle);
+
+    Number const serviceFee = loan->at(sfLoanServiceFee);
+    ExtendedPaymentComponents const periodic{
+        computePaymentComponents(view.rules(), asset, loan, periodicRate, managementFeeRate),
+        serviceFee};
+    XRPL_ASSERT_PARTS(
+        periodic.trackedPrincipalDelta >= 0,
+        "xrpl::detail::makeLatePayment",
+        "regular payment valid principal");
+
+    auto const latePaymentComponents =
+        computeLatePayment(asset, view, loan, periodic, amount, managementFeeRate, j);
+
+    // computeLatePayment only ever fails with a genuine error TER (never
+    // tesSUCCESS), so there is no separate "no-op" outcome to handle here.
+    if (latePaymentComponents.has_value())
+        return doPayment(*latePaymentComponents, loan);
+    return std::unexpected(latePaymentComponents.error());
+}
+
+/* Handles regular scheduled payments, including an optional overpayment tail.
+ * Implements the "regular" and "overpayment" branches of the make_payment
+ * function from the XLS-66 spec, Section 3.2.4.4.
+ */
+std::expected<LoanPaymentParts, TER>
+makeRegularPayment(
+    Asset const& asset,
+    ApplyView const& view,
+    SLE::ref loan,
+    SLE::const_ref brokerSle,
+    STAmount const& amount,
+    LoanPaymentType const paymentType,
+    beast::Journal j)
+{
+    using namespace Lending;
+
+    XRPL_ASSERT_PARTS(
+        paymentType == LoanPaymentType::Regular || paymentType == LoanPaymentType::Overpayment,
+        "xrpl::detail::makeRegularPayment",
+        "regular payment type");
+
+    auto const [managementFeeRate, periodicRate] = loanRatesFor(loan, brokerSle);
+
+    std::int32_t const loanScale = loan->at(sfLoanScale);
+    Number const serviceFee = loan->at(sfLoanServiceFee);
+
+    ExtendedPaymentComponents periodic{
+        computePaymentComponents(view.rules(), asset, loan, periodicRate, managementFeeRate),
+        serviceFee};
+    XRPL_ASSERT_PARTS(
+        periodic.trackedPrincipalDelta >= 0,
+        "xrpl::detail::makeRegularPayment",
+        "regular payment valid principal");
+
+    // Keep a running total of the actual parts paid
+    LoanPaymentParts totalParts;
+    Number totalPaid = kNumZero;
+    std::size_t numPayments = 0;
+
+    // Cached here (rather than re-looking up loan->at(sfPaymentRemaining) at each use) since it's
+    // read multiple times below. It's a write-through proxy, so it still reflects doPayment's
+    // mutations each iteration.
+    auto paymentRemainingProxy = loan->at(sfPaymentRemaining);
+
+    while ((amount >= (totalPaid + periodic.totalDue)) && paymentRemainingProxy > 0 &&
+           numPayments < kLoanMaximumPaymentsPerTransaction)
+    {
+        // Try to make more payments
+        XRPL_ASSERT_PARTS(
+            periodic.trackedPrincipalDelta >= 0,
+            "xrpl::detail::makeRegularPayment",
+            "payment pays non-negative principal");
+
+        totalPaid += periodic.totalDue;
+        totalParts += doPayment(periodic, loan);
+        ++numPayments;
+
+        XRPL_ASSERT_PARTS(
+            (periodic.specialCase == PaymentSpecialCase::Final) == (paymentRemainingProxy == 0),
+            "xrpl::detail::makeRegularPayment",
+            "final payment is the final payment");
+
+        // Don't compute the next payment if this was the last payment
+        if (periodic.specialCase == PaymentSpecialCase::Final)
+            break;
+
+        periodic = ExtendedPaymentComponents{
+            computePaymentComponents(view.rules(), asset, loan, periodicRate, managementFeeRate),
+            serviceFee};
+    }
+
+    if (numPayments == 0)
+    {
+        JLOG(j.warn()) << "Regular loan payment amount is insufficient. Due: " << periodic.totalDue
+                       << ", paid: " << amount;
+        return std::unexpected(tecINSUFFICIENT_PAYMENT);
+    }
+
+    XRPL_ASSERT_PARTS(
+        totalParts.principalPaid + totalParts.interestPaid + totalParts.feePaid == totalPaid,
+        "xrpl::detail::makeRegularPayment",
+        "payment parts add up");
+    XRPL_ASSERT_PARTS(
+        totalParts.valueChange == 0, "xrpl::detail::makeRegularPayment", "no value change");
+
+    // -------------------------------------------------------------
+    // overpayment handling
+    //
+    // If the "fixCleanup3_1_3" amendment is enabled, truncate "amount",
+    // at the loan scale. If the raw value is used, the overpayment
+    // amount could be meaningless dust. Trying to process such a small
+    // amount will, at best, waste time when all the result values round
+    // to zero. At worst, it can cause logical errors with tiny amounts
+    // of interest that don't add up correctly.
+    auto const roundedAmount = view.rules().enabled(fixCleanup3_1_3)
+        ? roundToAsset(asset, amount, loanScale, Number::RoundingMode::TowardsZero)
+        : amount;
+
+    bool const overpaymentSupported =
+        paymentType == LoanPaymentType::Overpayment && loan->isFlag(lsfLoanOverpayment);
+
+    bool const overpaymentAllowed =   //
+        paymentRemainingProxy > 0 &&  //
+        totalPaid < roundedAmount &&  //
+        numPayments < kLoanMaximumPaymentsPerTransaction;
+
+    if (overpaymentSupported && overpaymentAllowed)
+    {
+        TenthBips32 const overpaymentInterestRate{loan->at(sfOverpaymentInterestRate)};
+        TenthBips32 const overpaymentFeeRate{loan->at(sfOverpaymentFee)};
+
+        // 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 overpaymentRaw =
+            std::min(roundedAmount - totalPaid, *loan->at(sfTotalValueOutstanding));
+
+        bool const fixEnabled = view.rules().enabled(fixCleanup3_2_0);
+        Number const overpayment = fixEnabled
+            ? roundToAsset(asset, overpaymentRaw, loanScale, Number::RoundingMode::Downward)
+            : overpaymentRaw;
+
+        // Post-amendment, the rounded overpayment can be zero; pre-amendment
+        // it's always positive given the surrounding guards.
+        if (!fixEnabled || overpayment > 0)
+        {
+            ExtendedPaymentComponents const overpaymentComponents = computeOverpaymentComponents(
+                view.rules(),
+                asset,
+                loanScale,
+                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)
+            {
+                XRPL_ASSERT_PARTS(
+                    overpaymentComponents.untrackedInterest >= beast::kZero,
+                    "xrpl::detail::makeRegularPayment",
+                    "overpayment penalty did not reduce value of loan");
+                if (auto const overResult = doOverpayment(
+                        view.rules(),
+                        asset,
+                        loanScale,
+                        overpaymentComponents,
+                        loan,
+                        periodicRate,
+                        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 std::unexpected(overResult.error());
+                }
+            }
+        }
+    }
+
+    // Check the final results are rounded, to double-check that the
+    // intermediate steps were rounded.
+    XRPL_ASSERT(
+        isRounded(asset, totalParts.principalPaid, loanScale) &&
+            totalParts.principalPaid >= beast::kZero,
+        "xrpl::detail::makeRegularPayment : total principal paid is valid");
+    XRPL_ASSERT(
+        isRounded(asset, totalParts.interestPaid, loanScale) &&
+            totalParts.interestPaid >= beast::kZero,
+        "xrpl::detail::makeRegularPayment : total interest paid is valid");
+    XRPL_ASSERT(
+        isRounded(asset, totalParts.valueChange, loanScale),
+        "xrpl::detail::makeRegularPayment : loan value change is valid");
+    XRPL_ASSERT(
+        isRounded(asset, totalParts.feePaid, loanScale) && totalParts.feePaid >= beast::kZero,
+        "xrpl::detail::makeRegularPayment : fee paid is valid");
+    return totalParts;
+}
+
 }  // namespace detail
 
 detail::LoanStateDeltas
@@ -1632,8 +1926,10 @@ constructLoanState(
 }
 
 LoanState
-constructRoundedLoanState(SLE::const_ref loan)
+constructLoanState(SLE::const_ref loan)
 {
+    XRPL_ASSERT(loan && loan->getType() == ltLOAN, "xrpl::constructLoanState : valid loan SLE");
+
     return constructLoanState(
         loan->at(sfTotalValueOutstanding),
         loan->at(sfPrincipalOutstanding),
@@ -1790,12 +2086,7 @@ loanMakePayment(
     LoanPaymentType const paymentType,
     beast::Journal j)
 {
-    using namespace Lending;
-
-    auto principalOutstandingProxy = loan->at(sfPrincipalOutstanding);
-    auto paymentRemainingProxy = loan->at(sfPaymentRemaining);
-
-    if (paymentRemainingProxy == 0 || principalOutstandingProxy == 0)
+    if (loan->at(sfPaymentRemaining) == 0 || loan->at(sfPrincipalOutstanding) == 0)
     {
         // Loan complete this is already checked in LoanPay::preclaim()
         // LCOV_EXCL_START
@@ -1804,9 +2095,6 @@ loanMakePayment(
         // LCOV_EXCL_STOP
     }
 
-    auto totalValueOutstandingProxy = loan->at(sfTotalValueOutstanding);
-    auto managementFeeOutstandingProxy = loan->at(sfManagementFeeOutstanding);
-
     // Next payment due date must be set unless the loan is complete
     auto nextDueDateProxy = loan->at(sfNextPaymentDueDate);
     if (*nextDueDateProxy == 0)
@@ -1815,26 +2103,8 @@ loanMakePayment(
         return std::unexpected(tecINTERNAL);
     }
 
-    std::int32_t const loanScale = loan->at(sfLoanScale);
-
-    TenthBips32 const interestRate{loan->at(sfInterestRate)};
-
-    Number const serviceFee = loan->at(sfLoanServiceFee);
-    TenthBips16 const managementFeeRate{brokerSle->at(sfManagementFeeRate)};
-
-    Number const periodicPayment = loan->at(sfPeriodicPayment);
-
-    auto prevPaymentDateProxy = loan->at(sfPreviousPaymentDueDate);
-    std::uint32_t const startDate = loan->at(sfStartDate);
-
-    std::uint32_t const paymentInterval = loan->at(sfPaymentInterval);
-
-    // Compute the periodic rate that will be used for calculations
-    // throughout
-    Number const periodicRate = loanPeriodicRate(interestRate, paymentInterval);
-    XRPL_ASSERT(interestRate == 0 || periodicRate > 0, "xrpl::loanMakePayment : valid rate");
-
-    XRPL_ASSERT(*totalValueOutstandingProxy > 0, "xrpl::loanMakePayment : valid total value");
+    XRPL_ASSERT(
+        *loan->at(sfTotalValueOutstanding) > 0, "xrpl::loanMakePayment : valid total value");
 
     view.update(loan);
 
@@ -1844,311 +2114,29 @@ loanMakePayment(
     {
         // If the payment is late, and the late flag was not set, it's not
         // valid
-        JLOG(j.warn()) << "Loan payment is overdue. Use the tfLoanLatePayment "
-                          "transaction "
-                          "flag to make a late payment. Loan was created on "
-                       << startDate << ", prev payment due date is " << prevPaymentDateProxy
-                       << ", next payment due date is " << nextDueDateProxy << ", ledger time is "
+        JLOG(j.warn()) << "Loan payment is overdue. Use the tfLoanLatePayment transaction flag to "
+                          "make a late payment. Loan was created on "
+                       << loan->at(sfStartDate) << ", prev payment due date is "
+                       << loan->at(sfPreviousPaymentDueDate) << ", next payment due date is "
+                       << nextDueDateProxy << ", ledger time is "
                        << view.parentCloseTime().time_since_epoch().count();
         return std::unexpected(tecEXPIRED);
     }
 
-    // -------------------------------------------------------------
-    // full payment handling
-    if (paymentType == LoanPaymentType::Full)
+    switch (paymentType)
     {
-        TenthBips32 const closeInterestRate{loan->at(sfCloseInterestRate)};
-        Number const closePaymentFee = roundToAsset(asset, loan->at(sfClosePaymentFee), loanScale);
-
-        LoanState const roundedLoanState = constructLoanState(
-            totalValueOutstandingProxy, principalOutstandingProxy, managementFeeOutstandingProxy);
-
-        auto const fullPaymentComponents = detail::computeFullPayment(
-            asset,
-            view,
-            principalOutstandingProxy,
-            managementFeeOutstandingProxy,
-            periodicPayment,
-            paymentRemainingProxy,
-            prevPaymentDateProxy,
-            startDate,
-            paymentInterval,
-            closeInterestRate,
-            loanScale,
-            roundedLoanState.interestDue,
-            periodicRate,
-            closePaymentFee,
-            amount,
-            managementFeeRate,
-            j);
-
-        if (fullPaymentComponents.has_value())
-        {
-            return doPayment(
-                *fullPaymentComponents,
-                totalValueOutstandingProxy,
-                principalOutstandingProxy,
-                managementFeeOutstandingProxy,
-                paymentRemainingProxy,
-                prevPaymentDateProxy,
-                nextDueDateProxy,
-                paymentInterval);
-        }
-
-        if (fullPaymentComponents.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 std::unexpected(fullPaymentComponents.error());
-        }
-
-        // LCOV_EXCL_START
-        UNREACHABLE("xrpl::loanMakePayment : invalid full payment result");
-        JLOG(j.error()) << "Full payment computation failed unexpectedly.";
-        return std::unexpected(tecINTERNAL);
-        // LCOV_EXCL_STOP
+        case LoanPaymentType::Full:
+            return detail::makeFullPayment(asset, view, loan, brokerSle, amount, j);
+        case LoanPaymentType::Late:
+            return detail::makeLatePayment(asset, view, loan, brokerSle, amount, j);
+        case LoanPaymentType::Regular:
+        case LoanPaymentType::Overpayment:
+            return detail::makeRegularPayment(asset, view, loan, brokerSle, amount, paymentType, j);
     }
 
-    // -------------------------------------------------------------
-    // compute the periodic payment info that will be needed whether the
-    // payment is late or regular
-    detail::ExtendedPaymentComponents periodic{
-        detail::computePaymentComponents(
-            view.rules(),
-            asset,
-            loanScale,
-            totalValueOutstandingProxy,
-            principalOutstandingProxy,
-            managementFeeOutstandingProxy,
-            periodicPayment,
-            periodicRate,
-            paymentRemainingProxy,
-            managementFeeRate),
-        serviceFee};
-    XRPL_ASSERT_PARTS(
-        periodic.trackedPrincipalDelta >= 0,
-        "xrpl::loanMakePayment",
-        "regular payment valid principal");
-
-    // -------------------------------------------------------------
-    // late payment handling
-    if (paymentType == LoanPaymentType::Late)
-    {
-        TenthBips32 const lateInterestRate{loan->at(sfLateInterestRate)};
-        Number const latePaymentFee = loan->at(sfLatePaymentFee);
-
-        auto const latePaymentComponents = detail::computeLatePayment(
-            asset,
-            view,
-            principalOutstandingProxy,
-            nextDueDateProxy,
-            periodic,
-            lateInterestRate,
-            loanScale,
-            latePaymentFee,
-            amount,
-            managementFeeRate,
-            j);
-
-        if (latePaymentComponents.has_value())
-        {
-            return doPayment(
-                *latePaymentComponents,
-                totalValueOutstandingProxy,
-                principalOutstandingProxy,
-                managementFeeOutstandingProxy,
-                paymentRemainingProxy,
-                prevPaymentDateProxy,
-                nextDueDateProxy,
-                paymentInterval);
-        }
-
-        if (latePaymentComponents.error())
-        {
-            // error() will be the TER returned if a payment is not made. It
-            // will only evaluate to true if it's unsuccessful.
-            return std::unexpected(latePaymentComponents.error());
-        }
-
-        // LCOV_EXCL_START
-        UNREACHABLE("xrpl::loanMakePayment : invalid late payment result");
-        JLOG(j.error()) << "Late payment computation failed unexpectedly.";
-        return std::unexpected(tecINTERNAL);
-        // LCOV_EXCL_STOP
-    }
-
-    // -------------------------------------------------------------
-    // regular periodic payment handling
-
-    XRPL_ASSERT_PARTS(
-        paymentType == LoanPaymentType::Regular || paymentType == LoanPaymentType::Overpayment,
-        "xrpl::loanMakePayment",
-        "regular payment type");
-
-    // Keep a running total of the actual parts paid
-    LoanPaymentParts totalParts;
-    Number totalPaid;
-    std::size_t numPayments = 0;
-
-    while ((amount >= (totalPaid + periodic.totalDue)) && paymentRemainingProxy > 0 &&
-           numPayments < kLoanMaximumPaymentsPerTransaction)
-    {
-        // Try to make more payments
-        XRPL_ASSERT_PARTS(
-            periodic.trackedPrincipalDelta >= 0,
-            "xrpl::loanMakePayment",
-            "payment pays non-negative principal");
-
-        totalPaid += periodic.totalDue;
-        totalParts += detail::doPayment(
-            periodic,
-            totalValueOutstandingProxy,
-            principalOutstandingProxy,
-            managementFeeOutstandingProxy,
-            paymentRemainingProxy,
-            prevPaymentDateProxy,
-            nextDueDateProxy,
-            paymentInterval);
-        ++numPayments;
-
-        XRPL_ASSERT_PARTS(
-            (periodic.specialCase == detail::PaymentSpecialCase::Final) ==
-                (paymentRemainingProxy == 0),
-            "xrpl::loanMakePayment",
-            "final payment is the final payment");
-
-        // Don't compute the next payment if this was the last payment
-        if (periodic.specialCase == detail::PaymentSpecialCase::Final)
-            break;
-
-        periodic = detail::ExtendedPaymentComponents{
-            detail::computePaymentComponents(
-                view.rules(),
-                asset,
-                loanScale,
-                totalValueOutstandingProxy,
-                principalOutstandingProxy,
-                managementFeeOutstandingProxy,
-                periodicPayment,
-                periodicRate,
-                paymentRemainingProxy,
-                managementFeeRate),
-            serviceFee};
-    }
-
-    if (numPayments == 0)
-    {
-        JLOG(j.warn()) << "Regular loan payment amount is insufficient. Due: " << periodic.totalDue
-                       << ", paid: " << amount;
-        return std::unexpected(tecINSUFFICIENT_PAYMENT);
-    }
-
-    XRPL_ASSERT_PARTS(
-        totalParts.principalPaid + totalParts.interestPaid + totalParts.feePaid == totalPaid,
-        "xrpl::loanMakePayment",
-        "payment parts add up");
-    XRPL_ASSERT_PARTS(totalParts.valueChange == 0, "xrpl::loanMakePayment", "no value change");
-
-    // -------------------------------------------------------------
-    // overpayment handling
-    //
-    // If the "fixCleanup3_1_3" amendment is enabled, truncate "amount",
-    // at the loan scale. If the raw value is used, the overpayment
-    // amount could be meaningless dust. Trying to process such a small
-    // amount will, at best, waste time when all the result values round
-    // to zero. At worst, it can cause logical errors with tiny amounts
-    // of interest that don't add up correctly.
-    auto const roundedAmount = view.rules().enabled(fixCleanup3_1_3)
-        ? roundToAsset(asset, amount, loanScale, Number::RoundingMode::TowardsZero)
-        : amount;
-    if (paymentType == LoanPaymentType::Overpayment && loan->isFlag(lsfLoanOverpayment) &&
-        paymentRemainingProxy > 0 && totalPaid < roundedAmount &&
-        numPayments < kLoanMaximumPaymentsPerTransaction)
-    {
-        TenthBips32 const overpaymentInterestRate{loan->at(sfOverpaymentInterestRate)};
-        TenthBips32 const overpaymentFeeRate{loan->at(sfOverpaymentFee)};
-
-        // 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 overpaymentRaw =
-            std::min(roundedAmount - totalPaid, *totalValueOutstandingProxy);
-
-        bool const fixEnabled = view.rules().enabled(fixCleanup3_2_0);
-        Number const overpayment = fixEnabled
-            ? roundToAsset(asset, overpaymentRaw, loanScale, Number::RoundingMode::Downward)
-            : overpaymentRaw;
-
-        // Post-amendment, the rounded overpayment can be zero; pre-amendment
-        // it's always positive given the surrounding guards.
-        if (!fixEnabled || overpayment > 0)
-        {
-            detail::ExtendedPaymentComponents const overpaymentComponents =
-                detail::computeOverpaymentComponents(
-                    view.rules(),
-                    asset,
-                    loanScale,
-                    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)
-            {
-                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 std::unexpected(overResult.error());
-                }
-            }
-        }
-    }
-
-    // Check the final results are rounded, to double-check that the
-    // intermediate steps were rounded.
-    XRPL_ASSERT(
-        isRounded(asset, totalParts.principalPaid, loanScale) &&
-            totalParts.principalPaid >= beast::kZero,
-        "xrpl::loanMakePayment : total principal paid is valid");
-    XRPL_ASSERT(
-        isRounded(asset, totalParts.interestPaid, loanScale) &&
-            totalParts.interestPaid >= beast::kZero,
-        "xrpl::loanMakePayment : total interest paid is valid");
-    XRPL_ASSERT(
-        isRounded(asset, totalParts.valueChange, loanScale),
-        "xrpl::loanMakePayment : loan value change is valid");
-    XRPL_ASSERT(
-        isRounded(asset, totalParts.feePaid, loanScale) && totalParts.feePaid >= beast::kZero,
-        "xrpl::loanMakePayment : fee paid is valid");
-    return totalParts;
+    // LCOV_EXCL_START
+    UNREACHABLE("xrpl::loanMakePayment : invalid payment type");
+    return std::unexpected(tecINTERNAL);
+    // LCOV_EXCL_STOP
 }
 }  // namespace xrpl