Fix clippy and doc test errors

develop changed every sequence-based `keylet::` factory to take
`SeqProxy const&` instead of `std::uint32_t`, and removed the
two-argument `mptokenIssuance(seq, issuer)` overload. The wasm host
functions and their tests still passed raw sequences, so the branch
merged cleanly but did not compile.

Wrap the raw sequences at the call sites, matching the idiom develop
adopted in its own tests:

- `SeqProxy::rawSequence` for check, escrow, nftokenOffer, offer,
  payChannel, permissionedDomain and vault
- `SeqProxy::rawTicket` for ticket
- `keylet::mptokenIssuance(makeMptID(seq, issuer))` for the removed
  overload

No computed keylet changes: the factories only read `seq.value()`, and
the removed overload was itself defined as `mptokenIssuance(makeMptID(
seq, issuer))`.

.clang-tidy

@@ -90,13 +90,6 @@ CheckOptions:
   readability-identifier-naming.ClassCase: CamelCase
   readability-identifier-naming.StructCase: CamelCase
   readability-identifier-naming.UnionCase: CamelCase
-  readability-identifier-naming.TypeAliasCase: CamelCase
-  readability-identifier-naming.TypedefCase: CamelCase
-  # Member type names mandated by std/Boost concepts. Subtrees that need more
-  # than these carry their own .clang-tidy (include/xrpl/{beast,basics,protocol,
-  # peerfinder}, src/test/beast); one-off cases use an inline NOLINT.
-  readability-identifier-naming.TypeAliasIgnoredRegexp: "^(const_iterator|const_reference|difference_type|duration|iterator|iterator_category|key_type|mapped_type|period|pointer|reference|rep|result_type|size_type|time_point|value_type)$"
-  readability-identifier-naming.TypedefIgnoredRegexp: "^(const_iterator|const_reference|difference_type|duration|iterator|iterator_category|key_type|mapped_type|period|pointer|reference|rep|result_type|size_type|time_point|value_type)$"
   readability-identifier-naming.EnumCase: CamelCase
   readability-identifier-naming.EnumConstantCase: CamelCase
   readability-identifier-naming.ScopedEnumConstantCase: CamelCase
@@ -129,5 +122,5 @@ CheckOptions:
   readability-identifier-naming.GlobalFunctionIgnoredRegexp: "^(to_string|hash_append|tuple_hash)$"
 
 HeaderFilterRegex: '^.*/(tests?|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
-ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$|^.*\.pb\.h$'
+ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$'
 WarningsAsErrors: "*"

.cspell.config.yaml

@@ -7,7 +7,6 @@ ignorePaths:
   - cmake/**
   - LICENSE.md
   - .clang-tidy
-  - nix/check-tools/*.txt # generated, and full of Nix store hashes
 language: en
 allowCompoundWords: true # TODO (#6334)
 ignoreRandomStrings: true
@@ -64,13 +63,12 @@ words:
   - blindings
   - bookdir
   - Bougalis
-  - bthomee
   - Britto
   - Btrfs
   - Buildx
   - canonicality
+  - cdylib
   - canonicalised
-  - cctools
   - changespq
   - checkme
   - choco
@@ -106,13 +104,13 @@ words:
   - deleteme
   - demultiplexer
   - deserializaton
+  - desugars
   - desync
   - desynced
   - determ
   - disablerepo
   - distro
   - doxyfile
-  - dsymutil
   - dxrpl
   - elgamal
   - enabled
@@ -132,6 +130,7 @@ words:
   - gcov
   - gcovr
   - ghead
+  - gmock
   - Gnutella
   - godexsoft
   - gpgcheck
@@ -141,8 +140,9 @@ words:
   - hwaddress
   - hwrap
   - ifndef
+  - impls
   - inequation
-  - Injectivity
+  - initialiser
   - insuf
   - insuff
   - invasively
@@ -172,7 +172,6 @@ words:
   - LOCALGOOD
   - logwstream
   - Lombrozo
-  - lresolv
   - lseq
   - lsmf
   - ltype
@@ -226,7 +225,6 @@ words:
   - Nyffenegger
   - onlatest
   - ostr
-  - otool
   - oxalica
   - pargs
   - partitioner
@@ -252,20 +250,16 @@ words:
   - pyparsing
   - qalloc
   - qbsprofile
+  - qself
   - queuable
   - Raphson
   - rcflags
-  - reencrypted
   - replayer
-  - repodata
-  - repomd
   - rerandomize
   - rerandomization
   - rerandomized
   - rerandomizes
   - rerere
-  - retargeted
-  - retargets
   - retriable
   - RIPD
   - ripdtop
@@ -301,7 +295,6 @@ words:
   - sles
   - soci
   - socidb
-  - Sonatype
   - sponsee
   - sponsees
   - SRPMS
@@ -310,6 +303,7 @@ words:
   - STATSDCOLLECTOR
   - stissue
   - stnum
+  - stnumber
   - stobj
   - stobject
   - stpath
@@ -350,6 +344,7 @@ words:
   - unflatten
   - unfund
   - unimpair
+  - unmetered
   - unroutable
   - unscalable
   - unserviced
@@ -370,6 +365,7 @@ words:
   - vfalco
   - vinnie
   - wasmi
+  - Werror
   - wextra
   - wptr
   - writeme
@@ -377,16 +373,13 @@ words:
   - wthread
   - xbridge
   - xchain
-  - xcrun
+  - xfloat
   - ximinez
   - XMACRO
-  - xored
   - xrpkuwait
   - xrpl
   - xrpld
   - xrplf
   - xxhash
   - xxhasher
-  - zstdio
   - CGNAT
-  - ungated

.envrc

@@ -1,14 +1,3 @@
 watch_file nix/*.nix
 
-# Pinned Rust toolchain, read by nix/packages.nix via fromRustupToolchainFile.
-watch_file rust-toolchain.toml
-
-# The dev shell derivation includes all of conan/ (see nix/devshell.nix), so any
-# change in there has to invalidate direnv's cached environment.
-watch_dir conan
-
 use flake
-
-# Optional, untracked local overrides. To use a different shell, put e.g.
-# `use flake .#formal-verification` in .envrc.local.
-source_env_if_exists .envrc.local

.git-blame-ignore-revs

@@ -5,18 +5,6 @@
 # This file is sorted in reverse chronological order, with the most recent commits at the top.
 # The commits listed here are ignored by git blame, which is useful for formatting-only commits that would otherwise obscure the history of changes to a file.
 
-# chore: CamelCase for typedef/using in `clang-tidy` (#8177)
-97a1824537d20d82d25bf151a37a7a4532ebf085
-# chore: Rename CamelCase namespaces to snake_case (#7933)
-06488c1318d96f56d0536251bee08ac85fa7fdd3
-# style: Unify style for all Doxygen comments (#7776)
-73b6852a122854140336e6e6bc30a3a4b41aa5fd
-# style: More clang-tidy identifier renaming (#7290)
-a830ab10efed8d3e59ef2fc15d66efdf9c6bb0d8
-# refactor: Rename static constants (#7120)
-5b6e8b6f93b19c1e3f6a3467a25639031d9d9a53
-# chore: More fixes for bad renames (#7092)
-7afdd71a54d562b32a50b29a5aa00bb997dc9053
 # refactor: Enable clang-tidy `readability-identifier-naming` check (#6571)
 8995564ed6b9e453e144bb663303072a3c1ba305
 # refactor: Enable remaining clang-tidy `cppcoreguidelines` checks (#6538)

.github/actions/cargo-cache/action.yml

@@ -1,39 +0,0 @@
-name: Use cargo artifacts cache
-description: >
-  Cache the cargo build artifacts with rust-cache. Never caches ~/.cargo/bin:
-  when saving the cache, rust-cache deletes all binaries that were already
-  present there, which on persistent self-hosted runners wipes the tools
-  installed by prepare-runner. Harmless on ephemeral runners, but kept
-  consistent everywhere.
-
-inputs:
-  workspaces:
-    description: "Workspaces to cache, as 'workspace -> target' lines."
-    required: false
-    default: crates
-  key:
-    description: "Additional part of the cache key."
-    required: false
-    default: ""
-  cache-directories:
-    description: "Additional non-workspace directories to cache."
-    required: false
-    default: ""
-  save-if:
-    description: >
-      Condition for saving the cache after the job. Defaults to save only from develop branch
-    required: false
-    default: ${{ github.ref == 'refs/heads/develop' }}
-
-runs:
-  using: composite
-
-  steps:
-    - name: Use cargo artifacts cache
-      uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
-      with:
-        cache-bin: "false"
-        cache-directories: ${{ inputs.cache-directories }}
-        key: ${{ inputs.key }}
-        save-if: ${{ inputs.save-if }}
-        workspaces: ${{ inputs.workspaces }}

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

@@ -0,0 +1,44 @@
+name: Generate build version number
+description: "Generate build version number."
+
+outputs:
+  version:
+    description: "The generated build version number."
+    value: ${{ steps.version.outputs.version }}
+
+runs:
+  using: composite
+  steps:
+    # When a tag is pushed, the version is used as-is.
+    - name: Generate version for tag event
+      if: ${{ startsWith(github.ref, 'refs/tags/') }}
+      shell: bash
+      env:
+        VERSION: ${{ github.ref_name }}
+      run: echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
+
+    # When a tag is not pushed, then the version (e.g. 1.2.3-b0) is extracted
+    # from the BuildInfo.cpp file and the shortened commit hash appended to it.
+    # We use a plus sign instead of a hyphen because Conan recipe versions do
+    # not support two hyphens.
+    - name: Generate version for non-tag event
+      if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      shell: bash
+      run: |
+        echo 'Extracting version from BuildInfo.cpp.'
+        VERSION="$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')"
+        if [[ -z "${VERSION}" ]]; then
+            echo 'Unable to extract version from BuildInfo.cpp.'
+            exit 1
+        fi
+
+        echo 'Appending shortened commit hash to version.'
+        SHA='${{ github.sha }}'
+        VERSION="${VERSION}+${SHA:0:7}"
+
+        echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
+
+    - name: Output version
+      id: version
+      shell: bash
+      run: echo "version=${VERSION}" >>"${GITHUB_OUTPUT}"

.github/actions/release-info/action.yml

@@ -1,39 +0,0 @@
-name: Release info
-description: "Derive the version, release channel and package release number for this build."
-
-outputs:
-  version:
-    description: "The build version number."
-    value: ${{ steps.version.outputs.version }}
-  channel:
-    description: "The release channel this build belongs to."
-    value: ${{ steps.release_info.outputs.channel }}
-  pkg_release:
-    description: "The package release number: 1 for a tag, <run number>.<commit date>git<short commit hash> otherwise."
-    value: ${{ steps.release_info.outputs.pkg_release }}
-
-runs:
-  using: composite
-  steps:
-    # A tag names its own version. Anything else is a development build named by
-    # its commit hash, matching what cmake/XrplVersion.cmake derives: the head of
-    # a pull request rather than the merge commit GitHub creates for it.
-    - name: Determine version
-      id: version
-      shell: bash
-      env:
-        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
-        REF_NAME: ${{ github.ref_name }}
-        SHA: ${{ github.event.pull_request.head.sha || github.sha }}
-      run: |
-        if [[ "${IS_TAG}" == "true" ]]; then
-            version="${REF_NAME}"
-        else
-            version="0.0.0-dev+${SHA:0:7}"
-        fi
-
-        echo "version=${version}" | tee -a "${GITHUB_OUTPUT}"
-
-    - name: Determine release channel and package release
-      id: release_info
-      uses: XRPLF/actions/release-info@a9f2eeca6fb3980ba3a84cf68566f1c69ad30674

.github/actions/setup-nix-env/action.yml

@@ -1,70 +0,0 @@
-name: Setup Nix environment
-description: "Build the flake's CI environment and put its tools on PATH."
-
-# The environment from nix/ci-env.nix, the same one the Linux CI images bake in
-# (see nix/docker). Exported onto PATH rather than entered with `nix develop`:
-# the composite actions below run plain `bash` and would escape a dev shell.
-
-runs:
-  using: composite
-
-  steps:
-    - name: Build the CI environment
-      id: build
-      shell: bash
-      env:
-        # --out-link doubles as a GC root for the length of the job.
-        OUT_LINK: ${{ runner.temp }}/xrpld-ci-env
-      run: |
-        # --extra-experimental-features: flakes may not be on in the runner's nix.conf.
-        nix --extra-experimental-features "nix-command flakes" \
-            build .#default --out-link "${OUT_LINK}" --print-build-logs
-        echo "path=$(readlink -f "${OUT_LINK}")" >>"${GITHUB_OUTPUT}"
-
-    - name: Export the environment
-      shell: bash
-      env:
-        ENV_PATH: ${{ steps.build.outputs.path }}
-      run: |
-        echo "${ENV_PATH}/bin" >>"${GITHUB_PATH}"
-
-        # Already KEY=VALUE per line. See `darwinEnv` in nix/ci-env.nix.
-        ENV_FILE="${ENV_PATH}/share/xrpld-ci-env/env"
-        if [ -f "${ENV_FILE}" ]; then
-            cat "${ENV_FILE}" >>"${GITHUB_ENV}"
-        fi
-
-        # XrplSanity.cmake otherwise rejects a Nix compiler as one that leaked.
-        echo "XRPL_DEVSHELL=ci-env" >>"${GITHUB_ENV}"
-
-        # Unlike the Linux nix images, macOS needs no SSL_CERT_FILE: it has its
-        # own trust store, and pinning would break TLS to hosts relying on it.
-
-        # In RUNNER_TEMP, which the runner empties per job, like the `.conan2`
-        # prepare-runner hands the system toolchain - but under its own name:
-        # that Conan is a different version, and the two would migrate each
-        # other's cache.
-        echo "CONAN_HOME=${RUNNER_TEMP}/.conan2-nix" >>"${GITHUB_ENV}"
-
-    # Config, profiles and remote, exactly as the dev shell sets them up on
-    # entry; the `setup-conan` action is skipped for this toolchain.
-    - name: Setup Conan
-      shell: bash
-      run: ./conan/init.sh
-
-    # `Check tools` runs later but swallows failures; a bad export would just
-    # build with the system toolchain.
-    - name: Verify the toolchain resolves into the Nix store
-      shell: bash
-      run: |
-        for tool in clang clang++ cmake ninja conan; do
-            path="$(command -v "${tool}" || true)"
-            echo "${tool} -> ${path:-<not found>}"
-            case "${path}" in
-                /nix/store/*) ;;
-                *)
-                    echo "::error::${tool} does not resolve into the Nix store"
-                    exit 1
-                    ;;
-            esac
-        done

.github/dependabot.yml

@@ -4,8 +4,7 @@ updates:
     directories:
       - /
       - .github/actions/build-deps/
-      - .github/actions/cargo-cache/
-      - .github/actions/release-info/
+      - .github/actions/generate-version/
       - .github/actions/set-compiler-env/
       - .github/actions/setup-conan/
     schedule:
@@ -29,9 +28,10 @@ updates:
       time: "04:00"
       timezone: Etc/GMT
     commit-message:
-      prefix: "chore: [DEPENDABOT] "
+      prefix: "ci: [DEPENDABOT] "
     target-branch: develop
     open-pull-requests-limit: 10
+    # Bundle all Rust dependency bumps into a single PR per run to reduce noise.
     groups:
       rust-dependencies:
         patterns:

.github/pull_request_template.md

@@ -18,7 +18,7 @@ If too broad, please consider splitting into multiple PRs.
 If there is a relevant task or issue, please link it here.
 -->
 
-## Context of Change
+### Context of Change
 
 <!--
 Please include the context of a change.
@@ -29,7 +29,7 @@ If a refactor, how is this better than the previous implementation?
 If there is a spec or design document for this feature, please link it here.
 -->
 
-## API Impact
+### API Impact
 
 <!--
 Please check [x] relevant options, delete irrelevant ones.

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

@@ -82,6 +82,7 @@ test.app > xrpl.tx
 test.basics > test.jtx
 test.basics > xrpl.basics
 test.basics > xrpl.core
+test.basics > xrpld.rpc
 test.basics > xrpl.json
 test.basics > xrpl.protocol
 test.beast > xrpl.basics
@@ -112,7 +113,6 @@ test.jtx > xrpl.config
 test.jtx > xrpl.core
 test.jtx > xrpld.app
 test.jtx > xrpld.core
-test.jtx > xrpld.overlay
 test.jtx > xrpld.rpc
 test.jtx > xrpl.json
 test.jtx > xrpl.ledger
@@ -194,9 +194,6 @@ tests.libxrpl > xrpl.resource
 tests.libxrpl > xrpl.server
 tests.libxrpl > xrpl.shamap
 tests.libxrpl > xrpl.tx
-tests.xrpld > xrpld.rpc
-tests.xrpld > xrpl.json
-tests.xrpld > xrpl.protocol
 xrpl.conditions > xrpl.basics
 xrpl.conditions > xrpl.protocol
 xrpl.config > xrpl.basics
@@ -289,10 +286,10 @@ xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.config
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.app
+xrpld.perflog > xrpld.rpc
 xrpld.perflog > xrpl.json
 xrpld.perflog > xrpl.nodestore
 xrpld.perflog > xrpl.protocol
-xrpld.perflog > xrpl.server
 xrpld.rpc > xrpl.basics
 xrpld.rpc > xrpl.config
 xrpld.rpc > xrpl.core

.github/scripts/releasing/check-merge-back-commits.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-
-# Exit the script as soon as an error occurs.
-set -euo pipefail
-
-# This script fails if <head> merges a release back into <base>,
-# but also adds commits that aren't on a release or staging branch, see RELEASING.md.
-# Merge commits are allowed.
-# Usage: .github/scripts/releasing/check-merge-back-commits.sh <base> <head>
-
-if [ "$#" -ne 2 ]; then
-    echo "Usage: $0 <base> <head>"
-    exit 1
-fi
-
-BASE=$1
-HEAD=$2
-
-SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
-# shellcheck source=.github/scripts/releasing/common.sh
-source "${SCRIPT_DIR}/common.sh"
-load_release_branches
-
-# A PR is a merge-back if some of its commits are on a release or staging branch.
-PR_COUNT=$(git rev-list --no-merges --count "${BASE}..${HEAD}")
-NEW_COUNT=$(git rev-list --no-merges --count "${BASE}..${HEAD}" --not "${BRANCHES[@]}")
-if ((NEW_COUNT == PR_COUNT)); then
-    echo "This PR doesn't merge a release back."
-    exit 0
-fi
-if ((NEW_COUNT == 0)); then
-    echo "This merge-back adds no commits of its own."
-    exit 0
-fi
-
-echo "This PR merges a release back, but also adds commits that aren't on a release or staging branch:"
-git log --no-merges --format='  %h %s' "${BASE}..${HEAD}" --not "${BRANCHES[@]}"
-echo
-echo "Make these changes in a separate PR, see RELEASING.md."
-exit 1

.github/scripts/releasing/check-no-copied-release-commits.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-
-# Exit the script as soon as an error occurs.
-set -euo pipefail
-
-# This script fails if the commits in <base>..<head> copy commits from a release or staging branch
-# (e.g. by rebasing or cherry-picking them) instead of merging that branch, see RELEASING.md.
-# Commits are compared by patch-id,
-# and only against release and staging commits that <head> does not already contain.
-# Usage: .github/scripts/releasing/check-no-copied-release-commits.sh <base> <head>
-
-if [ "$#" -ne 2 ]; then
-    echo "Usage: $0 <base> <head>"
-    exit 1
-fi
-
-BASE=$1
-HEAD=$2
-
-patch_ids() {
-    git log --no-merges --patch --no-color --no-ext-diff "$@" | git patch-id --stable | sort
-}
-
-SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
-# shellcheck source=.github/scripts/releasing/common.sh
-source "${SCRIPT_DIR}/common.sh"
-load_release_branches
-
-# Each line is "<patch-id> <commit>".
-RELEASE_PATCHES=$(patch_ids "${BRANCHES[@]}" --not "${HEAD}")
-PR_PATCHES=$(patch_ids "${BASE}..${HEAD}")
-
-# Each line is "<patch-id> <release commit> <PR commit>".
-COPIES=$(join <(echo "${RELEASE_PATCHES}") <(echo "${PR_PATCHES}"))
-if [ -z "${COPIES}" ]; then
-    echo "No copied release commits found."
-    exit 0
-fi
-
-echo "These commits copy release commits instead of merging them:"
-while read -r _ RELEASE_COMMIT PR_COMMIT; do
-    echo "  $(git log -1 --format='%h %s' "${PR_COMMIT}") (copies ${RELEASE_COMMIT:0:10})"
-done <<<"${COPIES}"
-echo
-echo "Merge the release tag (or branch) instead, see RELEASING.md."
-exit 1

.github/scripts/releasing/check-no-merge-back.sh

@@ -1,38 +0,0 @@
-#!/usr/bin/env bash
-
-# Exit the script as soon as an error occurs.
-set -euo pipefail
-
-# This script fails if <head> contains release or staging commits that <base> does not,
-# i.e. if <head> merges a release back into <base>.
-# Used in the merge queue, which squashes PRs and would drop the merge commit, see RELEASING.md.
-# Usage: .github/scripts/releasing/check-no-merge-back.sh <base> <head>
-
-if [ "$#" -ne 2 ]; then
-    echo "Usage: $0 <base> <head>"
-    exit 1
-fi
-
-BASE=$1
-HEAD=$2
-
-SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
-# shellcheck source=.github/scripts/releasing/common.sh
-source "${SCRIPT_DIR}/common.sh"
-load_release_branches
-
-RELEASE_COMMITS=$(git rev-list "${BRANCHES[@]}" --not "${BASE}")
-HEAD_COMMITS=$(git rev-list "${BASE}..${HEAD}")
-# The release commits in <head>, newest first.
-MERGED=$(grep -xF -f <(echo "${RELEASE_COMMITS}") <<<"${HEAD_COMMITS}" || true)
-if [ -z "${MERGED}" ]; then
-    echo "No release commits are merged back."
-    exit 0
-fi
-
-echo "This PR merges $(wc -l <<<"${MERGED}" | tr -d ' ') release commits back, e.g.:"
-head -5 <<<"${MERGED}" | xargs git log --no-walk --format='  %h %s'
-echo
-echo "Merge-backs must not go through the merge queue, which squashes them."
-echo "Fast-forward develop to the PR branch instead, see RELEASING.md."
-exit 1

.github/scripts/releasing/check-releases-merged.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-
-# Exit the script as soon as an error occurs.
-set -euo pipefail
-
-# This script fails if a final release (a tag like 3.4.0) on a release branch
-# is not merged back into <develop> within a few days, see RELEASING.md.
-# Usage: .github/scripts/releasing/check-releases-merged.sh <develop>
-
-if [ "$#" -ne 1 ]; then
-    echo "Usage: $0 <develop>"
-    exit 1
-fi
-
-DEVELOP=$1
-GRACE_DAYS=3
-
-mapfile -t MERGED_ARGS < <(git for-each-ref --format='--merged=%(refname)' 'refs/remotes/*/release/*')
-if [ "${#MERGED_ARGS[@]}" -eq 0 ]; then
-    echo "Error: No release branches found."
-    exit 1
-fi
-
-# Tags on a release branch that <develop> does not contain.
-TAGS=$(git for-each-ref --format='%(refname:short) %(creatordate:unix)' \
-    "${MERGED_ARGS[@]}" --no-merged="${DEVELOP}" 'refs/tags/[0-9]*')
-
-MISSING=0
-while read -r TAG CREATED; do
-    if ! [[ "${TAG}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-        continue
-    fi
-    if (($(date +%s) - CREATED < GRACE_DAYS * 86400)); then
-        echo "${TAG}: not merged yet, still within the ${GRACE_DAYS}-day grace period."
-    else
-        echo "${TAG}: not merged into develop."
-        MISSING=1
-    fi
-done <<<"${TAGS}"
-
-if [ "${MISSING}" -ne 0 ]; then
-    echo
-    echo "Merge the missing releases back into develop, see RELEASING.md."
-    exit 1
-fi
-echo "No releases past the grace period are missing from develop."

.github/scripts/releasing/common.sh

@@ -1,12 +0,0 @@
-# shellcheck shell=bash
-
-# Helpers shared by the release checks in this directory, see RELEASING.md.
-
-# Sets BRANCHES to all release and staging branches, and fails if there are none.
-load_release_branches() {
-    mapfile -t BRANCHES < <(git for-each-ref --format='%(refname)' 'refs/remotes/*/release/*' 'refs/remotes/*/staging/*')
-    if [ "${#BRANCHES[@]}" -eq 0 ]; then
-        echo "Error: No release or staging branches found."
-        exit 1
-    fi
-}

.github/scripts/rename/binary.sh

@@ -49,7 +49,7 @@ ${SED_COMMAND} -i -E 's@ripple/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@xrpld \(`xrpld`\)@xrpld@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' CONTRIBUTING.md
-${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/install.md
+${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/build/install.md
 
 popd
 echo "Processing complete."

.github/scripts/rename/config.sh

@@ -62,7 +62,7 @@ ${SED_COMMAND} -i 's@ripple/@xrpld/@g' src/test/core/Config_test.cpp
 ${SED_COMMAND} -i 's/Rippled/File/g' src/test/core/Config_test.cpp
 
 # Restore the old config file name in the code that maintains support for now.
-${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/g' src/xrpld/core/Config.h
+${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/g' src/xrpld/core/detail/Config.cpp
 
 # Restore an URL.
 ${SED_COMMAND} -i 's/connect-your-xrpld-to-the-xrp-test-net.html/connect-your-rippled-to-the-xrp-test-net.html/g' cfg/xrpld-example.cfg

.github/scripts/rename/docs.sh

@@ -77,8 +77,8 @@ ${SED_COMMAND} -i 's/Ripple integrators/XRPL developers/' README.md
 ${SED_COMMAND} -i 's/sanitizer-configuration-for-rippled/sanitizer-configuration-for-xrpld/' docs/build/sanitizers.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/levelization/README.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/strategy-matrix/generate.py
-${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/install.md
-${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/install.md
+${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/build/install.md
+${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/build/install.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' docs/Doxyfile
 ${SED_COMMAND} -i 's/ripple_basics/basics/' include/xrpl/basics/CountedObject.h
 ${SED_COMMAND} -i 's/<ripple/<xrpl/' include/xrpl/protocol/AccountID.h
@@ -90,7 +90,7 @@ ${SED_COMMAND} -i 's/www.ripple.com/www.xrpl.org/g' src/test/protocol/Seed_test.
 # Restore specific changes.
 ${SED_COMMAND} -i 's@b5efcc/src/xrpld@b5efcc/src/ripple@' include/xrpl/protocol/README.md
 ${SED_COMMAND} -i 's/dbPrefix_ = "xrpldb"/dbPrefix_ = "rippledb"/' src/xrpld/app/misc/SHAMapStoreImp.h # cspell: disable-line
-${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/' src/xrpld/core/Config.h
+${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/' src/xrpld/core/detail/Config.cpp
 
 popd
 echo "Renaming complete."

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

@@ -7,21 +7,7 @@ from pathlib import Path
 
 THIS_DIR = Path(__file__).parent.resolve()
 
-_BASE_CMAKE_ARGS = [
-    "-Dtests=ON",
-    "-Dwerr=ON",
-    "-Dxrpld=ON",
-    "-Dwextra=ON",
-    "-Drust=ON",
-]
-
-# The package formats a config can be packaged as, each with its own
-# install-test job in reusable-package.yml.
-PACKAGE_TYPES = ("deb", "rpm")
-
-# The package name a variant suffixes, as build_pkg.py's BASE_NAME spells it:
-# the two have to agree, or the artifact globs miss what was built.
-BASE_NAME = "xrpld"
+_BASE_CMAKE_ARGS = ["-Dtests=ON", "-Dwerr=ON", "-Dxrpld=ON", "-Dwextra=ON"]
 
 # Maps sanitizer names (as used in cmake) to short config-name suffixes.
 _SANITIZER_SUFFIX: dict[str, str] = {
@@ -31,19 +17,6 @@ _SANITIZER_SUFFIX: dict[str, str] = {
 }
 
 
-def config_name(
-    distro: str,
-    compiler: str,
-    build_type: str,
-    arch: str,
-    suffix: str = "",
-    sanitizer: str = "",
-) -> str:
-    """Name a config. Its artifacts are named after it, so packaging reuses this."""
-    parts = [s for s in [suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s]
-    return "-".join([f"{distro}-{compiler}-{build_type.lower()}-{arch}", *parts])
-
-
 def get_cmake_args(build_type: str, extra_args: str) -> str:
     """Get the full list of CMake arguments for a config."""
     args = _BASE_CMAKE_ARGS.copy()
@@ -58,37 +31,17 @@ def get_cmake_args(build_type: str, extra_args: str) -> str:
 
 
 # Every config must declare 'minimal'. Minimal configs form the reduced matrix
-# built for pull requests by default; the full matrix adds the rest.
+# 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.
 #
-# Configs may also opt into 'benchmark' to smoke-run the benchmarks, or carry a
-# 'package' map to be packaged as well. Note that either applies to every entry
-# a config expands into, so only set them on configs that expand to a single
-# combination.
-
-
-@dataclasses.dataclass
-class PackageConfig:
-    """The 'package' map of a config whose binaries are also packaged."""
-
-    type: str  # has to match what the image provides
-    # The packaging container image: a vanilla distro image, not the nix image
-    # the config itself builds in.
-    image: str
-    # A flavour of the package, named xrpld-<variant>, for a config whose
-    # binaries are not the plain release build. A variant needs no counterpart
-    # in the other format.
-    variant: str = ""
-
-    def __post_init__(self) -> None:
-        assert self.type in PACKAGE_TYPES, (
-            f"unsupported package type {self.type!r}: "
-            f"use one of {', '.join(PACKAGE_TYPES)}."
-        )
+# Configs may also opt into 'benchmark' to smoke-run the benchmarks. Note that
+# the flag applies to every entry a config expands into, so only set it on
+# configs that expand to a single combination.
 
 
 @dataclasses.dataclass
 class LinuxConfig:
-    """One entry in a linux.json 'configs' array."""
+    """One entry in linux.json's 'configs' or 'package_configs' arrays."""
 
     compiler: list[str]
     build_type: list[str]
@@ -98,11 +51,7 @@ class LinuxConfig:
     sanitizers: list[str] = dataclasses.field(default_factory=list)
     suffix: str = ""
     extra_cmake_args: str = ""
-    package: PackageConfig | None = None  # set to also package this config
-
-    def __post_init__(self) -> None:
-        if isinstance(self.package, dict):
-            self.package = PackageConfig(**self.package)
+    image: str = ""  # only used by package_configs entries
 
 
 @dataclasses.dataclass
@@ -111,16 +60,22 @@ class LinuxFile:
 
     image_tag: str
     configs: dict[str, list[LinuxConfig]]  # distro → configs
+    package_configs: dict[str, list[LinuxConfig]]  # distro → packaging configs
 
     @classmethod
     def load(cls, path: Path) -> "LinuxFile":
         data = json.loads(path.read_text())
+
+        def parse(section: dict) -> dict[str, list[LinuxConfig]]:
+            return {
+                distro: [LinuxConfig(**c) for c in cfgs]
+                for distro, cfgs in section.items()
+            }
+
         return cls(
             image_tag=data["image_tag"],
-            configs={
-                distro: [LinuxConfig(**c) for c in cfgs]
-                for distro, cfgs in data["configs"].items()
-            },
+            configs=parse(data["configs"]),
+            package_configs=parse(data.get("package_configs", {})),
         )
 
 
@@ -133,9 +88,6 @@ class PlatformConfig:
     build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
     benchmark: bool = False  # if true, smoke-run the benchmarks after testing
     extra_cmake_args: str = ""
-    # "" is the runner's system compiler, "nix" the flake's CI environment.
-    # macOS only: Linux always builds in a Nix image, Windows has no Nix.
-    toolchain: str = ""
 
     def __post_init__(self) -> None:
         if isinstance(self.build_type, str):
@@ -185,7 +137,6 @@ class MatrixEntry:
     sanitizers: str
     image: str = ""  # container image; empty for macOS/Windows (runs natively)
     compiler: str = ""  # compiler name ("gcc" or "clang"); empty for macOS/Windows
-    toolchain: str = ""  # "nix" for the flake's CI environment; see PlatformConfig
 
 
 @dataclasses.dataclass
@@ -195,9 +146,7 @@ class PackagingEntry:
     xrpld_artifact_name: str
     validator_keys_artifact_name: str
     image: str
-    package_type: str  # "deb" or "rpm"; drives the format-specific steps
-    package_variant: str  # passed to build_pkg.py --variant; empty for xrpld
-    package_name: str  # the name it builds under, which the artifact globs use
+    distro: str  # e.g. "debian" or "rhel"; drives package-format-specific steps
 
 
 # ---------------------------------------------------------------------------
@@ -238,9 +187,13 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
                 effective_sanitizers,
                 effective_archs.items(),
             ):
-                name = config_name(
-                    distro, compiler, build_type, arch, cfg.suffix, sanitizer
-                )
+                name = f"{distro}-{compiler}-{build_type.lower()}-{arch}"
+                suffix_parts = [
+                    s for s in [cfg.suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s
+                ]
+                if suffix_parts:
+                    name += "-" + "-".join(suffix_parts)
+
                 entries.append(
                     MatrixEntry(
                         config_name=name,
@@ -260,59 +213,33 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
 
 
 def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
-    """Generate the packaging matrix from the configs that carry a 'package' map.
+    """Generate the packaging matrix from a LinuxFile's package_configs section.
 
-    Packaging consumes the binaries that config's build job uploaded, so the
-    artifact names come from the same config name, and a packaged config is one
-    that passes -Dvalidator_keys=ON.
+    Packaging uses vanilla distro images (debian:bookworm, ubi9, …) instead of
+    the nix-based build images, because deb/rpm tooling (debhelper, rpm-build)
+    is taken from the distro's archive rather than from nixpkgs. Each config
+    entry carries its own 'image'.
 
-    Packaging itself runs in vanilla distro images (debian:trixie, almalinux:10)
-    instead of the nix-based build images, because deb/rpm tooling (debhelper,
-    rpm-build) is taken from the distro's archive rather than from nixpkgs.
+    The artifact names must match what the build job uploads: one artifact per
+    binary, each named after the build config.
     """
     entries = []
-    for distro, configs in linux.configs.items():
+    for distro, configs in linux.package_configs.items():
         for cfg in configs:
-            if cfg.package is None:
-                continue
-            for compiler, build_type, arch in itertools.product(
-                cfg.compiler, cfg.build_type, cfg.arch
-            ):
-                # The packaging workflow hardcodes an amd64 runner.
-                assert arch == "amd64", f"cannot package {distro} on {arch}"
-                name = config_name(distro, compiler, build_type, arch, cfg.suffix)
+            for compiler, build_type in itertools.product(cfg.compiler, cfg.build_type):
+                config_name = f"{distro}-{compiler}-{build_type.lower()}-amd64"
                 entries.append(
                     PackagingEntry(
-                        xrpld_artifact_name=f"xrpld-{name}",
-                        validator_keys_artifact_name=f"validator-keys-{name}",
-                        image=cfg.package.image,
-                        package_type=cfg.package.type,
-                        package_variant=cfg.package.variant,
-                        package_name=(
-                            f"{BASE_NAME}-{cfg.package.variant}"
-                            if cfg.package.variant
-                            else BASE_NAME
-                        ),
+                        xrpld_artifact_name=f"xrpld-{config_name}",
+                        validator_keys_artifact_name=f"validator-keys-{config_name}",
+                        image=cfg.image,
+                        distro=distro,
                     )
                 )
 
     return entries
 
 
-def package_names_by_type(entries: list[PackagingEntry]) -> dict[str, list[str]]:
-    """The names of the packages in 'entries', keyed by format.
-
-    Derived from the packaging matrix rather than listed again, so the packages
-    the install-test jobs look for are the packages that were built.
-    """
-    return {
-        package_type: sorted(
-            {e.package_name for e in entries if e.package_type == package_type}
-        )
-        for package_type in PACKAGE_TYPES
-    }
-
-
 def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]:
     """Expand a PlatformFile (macOS or Windows) into matrix entries.
 
@@ -326,12 +253,9 @@ def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]
         if minimal and not cfg.minimal:
             continue
         for build_type in cfg.build_type:
-            name = f"{platform_name}-{arch}-{build_type.lower()}"
-            if cfg.toolchain:
-                name += f"-{cfg.toolchain}"
             entries.append(
                 MatrixEntry(
-                    config_name=name,
+                    config_name=f"{platform_name}-{arch}-{build_type.lower()}",
                     cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
                     cmake_target="install" if is_windows else "all",
                     build_only=cfg.build_only,
@@ -339,7 +263,6 @@ def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]
                     build_type=build_type,
                     architecture=Architecture(platform=pf.platform, runner=pf.runner),
                     sanitizers="",
-                    toolchain=cfg.toolchain,
                 )
             )
     return entries
@@ -381,10 +304,6 @@ if __name__ == "__main__":
 
     if args.packaging:
         matrix = expand_linux_packaging(LinuxFile.load(THIS_DIR / "linux.json"))
-        # One list per format, so each install-test job installs the packages its
-        # own format produced.
-        for package_type, names in package_names_by_type(matrix).items():
-            print(f"{package_type}_package_names={json.dumps(names)}")
     else:
         if args.config in ("linux", None):
             matrix += expand_linux_matrix(

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

@@ -1,5 +1,5 @@
 {
-  "image_tag": "sha-060957e",
+  "image_tag": "sha-fecfc0c",
   "configs": {
     "ubuntu": [
       {
@@ -71,24 +71,7 @@
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "extra_cmake_args": "-Dvalidator_keys=ON",
-        "package": {
-          "type": "deb",
-          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-3a2d19f"
-        }
-      },
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Release"],
-        "arch": ["amd64"],
-        "minimal": false,
-        "suffix": "assert",
-        "extra_cmake_args": "-Dvalidator_keys=ON -Dassert=ON",
-        "package": {
-          "type": "deb",
-          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-3a2d19f",
-          "variant": "assert"
-        }
+        "extra_cmake_args": "-Dvalidator_keys=ON"
       }
     ],
 
@@ -98,11 +81,28 @@
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "extra_cmake_args": "-Dvalidator_keys=ON",
-        "package": {
-          "type": "rpm",
-          "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-3a2d19f"
-        }
+        "extra_cmake_args": "-Dvalidator_keys=ON"
+      }
+    ]
+  },
+  "package_configs": {
+    "debian": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-577d745"
+      }
+    ],
+
+    "rhel": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-577d745"
       }
     ]
   }

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

@@ -12,19 +12,6 @@
       "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
       "build_only": true,
       "minimal": false
-    },
-    {
-      "build_type": "Release",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "minimal": false
-    },
-    {
-      "build_type": "Debug",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "build_only": true,
-      "minimal": false
     }
   ]
 }

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

@@ -5,13 +5,14 @@ on:
     branches:
       - develop
     paths:
+      - ".github/workflows/build-nix-images.yml"
       - "flake.nix"
       - "flake.lock"
       - "rust-toolchain.toml"
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
-      - "!nix/check-tools/**"
+      - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "bin/install-sanitizer-libs.sh"
   pull_request:
@@ -23,7 +24,6 @@ on:
       - "nix/**"
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
-      - "!nix/check-tools/**"
       - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "bin/install-sanitizer-libs.sh"
@@ -58,7 +58,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@696384b292577293292daed06af0306d1b83bd7d
+    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

@@ -6,13 +6,13 @@ on:
       - develop
     paths:
       - ".github/workflows/build-packaging-images.yml"
-      - "bin/install-packaging-tools.sh"
-      - "package/images/packaging/**"
+      - "package/Dockerfile"
+      - "package/install-packaging-tools.sh"
   pull_request:
     paths:
       - ".github/workflows/build-packaging-images.yml"
-      - "bin/install-packaging-tools.sh"
-      - "package/images/packaging/**"
+      - "package/Dockerfile"
+      - "package/install-packaging-tools.sh"
   workflow_dispatch:
 
 concurrency:
@@ -33,17 +33,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Newest of each distro: these images only wrap pre-built binaries, so
-        # they set no floor for consumers. build_pkg.py pins the RPM dist tag.
         distro:
           - name: debian
-            base_image: debian:trixie
-          # AlmaLinux rather than UBI, which does not ship rpm-sign.
+            base_image: debian:bookworm
           - name: rhel
-            base_image: almalinux:10
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@696384b292577293292daed06af0306d1b83bd7d
+            base_image: registry.access.redhat.com/ubi9/ubi:latest
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/packaging-${{ matrix.distro.name }}
-      dockerfile: package/images/packaging/Dockerfile
+      dockerfile: package/Dockerfile
       base_image: ${{ matrix.distro.base_image }}
       push: ${{ github.event_name == 'push' }}

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

@@ -30,7 +30,7 @@ jobs:
     permissions:
       contents: read
       packages: write
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@696384b292577293292daed06af0306d1b83bd7d
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/pre-commit
       dockerfile: bin/pre-commit/Dockerfile

.github/workflows/cargo-audit.yml

@@ -1,3 +1,8 @@
+# This workflow audits the Rust dependencies in crates/ for known security
+# advisories using cargo-audit. It runs on a weekly schedule, whenever the
+# dependency graph changes (Cargo.lock / Cargo.toml), and on demand. On a
+# scheduled run, a failure opens a tracking issue (matching the clang-tidy
+# workflow's behavior); on push/PR it simply fails the check.
 name: Cargo audit
 
 on:
@@ -7,7 +12,7 @@ on:
   push:
     branches:
       - "develop"
-      - "release/*"
+      - "release*"
     paths:
       - "crates/**/Cargo.toml"
       - "crates/Cargo.lock"
@@ -34,14 +39,14 @@ permissions:
 jobs:
   audit:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-debian:sha-2e25435
     permissions:
       contents: read
       # Needed to open an issue on scheduled failures.
       issues: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Run cargo audit
         id: audit
@@ -76,5 +81,4 @@ jobs:
         if: ${{ steps.audit.outcome != 'success' }}
         run: |
           echo "cargo audit found advisories!"
-          cat /tmp/cargo-audit.txt
           exit 1

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

@@ -13,6 +13,7 @@ on:
       - ready_for_review
     branches:
       - develop
+      - "release-*"
       - "release/*"
       - "staging/*"
 

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

@@ -13,6 +13,7 @@ on:
       - ready_for_review
     branches:
       - develop
+      - "release-*"
       - "release/*"
       - "staging/*"
 

.github/workflows/check-releases-merged.yml

@@ -1,60 +0,0 @@
-# This workflow checks that every final release on a release branch
-# has been merged back into develop, see RELEASING.md.
-name: Check releases merged
-
-on:
-  schedule:
-    # 06:47 UTC every Monday.
-    - cron: "47 6 * * 1"
-  push:
-    branches:
-      - "develop"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  OUTPUT_FILE: /tmp/releases-merged.txt
-  ISSUE_FILE: /tmp/releases-merged-issue.md
-
-jobs:
-  releases-merged:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      # Needed to open an issue on scheduled failures.
-      issues: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          # The check needs the full history of develop, the release branches and tags.
-          fetch-depth: 0
-
-      - name: Check releases are merged into develop
-        run: |
-          set -o pipefail
-          .github/scripts/releasing/check-releases-merged.sh origin/develop | tee "${OUTPUT_FILE}"
-
-      - name: Prepare issue body
-        if: ${{ failure() && github.event_name == 'schedule' && github.repository == 'XRPLF/rippled' }}
-        run: |
-          {
-              echo '```'
-              cat "${OUTPUT_FILE}"
-              echo '```'
-          } >"${ISSUE_FILE}"
-
-      - name: Create issue
-        if: ${{ failure() && github.event_name == 'schedule' && github.repository == 'XRPLF/rippled' }}
-        uses: XRPLF/actions/create-issue@2b8bc36af85b88bca0dd7bfac2e2dc05f94ad712
-        with:
-          title: "Releases not merged back into develop"
-          body_file: ${{ env.ISSUE_FILE }}
-          labels: "Bug"

.github/workflows/check-tools.yml

@@ -79,7 +79,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 

.github/workflows/on-pr.yml

@@ -77,15 +77,13 @@ jobs:
 
             # Keep the paths below in sync with those in `on-trigger.yml`.
             .github/actions/build-deps/**
-            .github/actions/release-info/**
+            .github/actions/generate-version/**
             .github/actions/setup-conan/**
-            .github/actions/setup-nix-env/**
             .github/scripts/strategy-matrix/**
             .github/workflows/reusable-build-test-config.yml
             .github/workflows/reusable-build-test.yml
             .github/workflows/reusable-check-autogen.yml
             .github/workflows/reusable-clang-tidy.yml
-            .github/workflows/reusable-package-test-install.yml
             .github/workflows/reusable-package.yml
             .github/workflows/reusable-rust.yml
             .github/workflows/reusable-strategy-matrix.yml
@@ -93,7 +91,6 @@ jobs:
             .github/workflows/reusable-upload-recipe.yml
             .clang-tidy
             .codecov.yml
-            bin/check-nix-store-refs.sh
             bin/check-tools.sh
             bin/default-loader-path.sh
             cfg/**
@@ -107,9 +104,6 @@ jobs:
             CMakeLists.txt
             conanfile.py
             conan.lock
-            flake.lock
-            flake.nix
-            nix/**
             LICENSE.md
             package/**
             README.md
@@ -150,48 +144,6 @@ jobs:
     if: ${{ needs.should-run.outputs.go == 'true' }}
     uses: ./.github/workflows/reusable-check-rename.yml
 
-  # Runs regardless of the changed files.
-  # PRs into staging branches are skipped, since fixes may be cherry-picked between release lines.
-  check-release-commits:
-    needs: should-run
-    if: ${{ github.event.pull_request.base.ref == 'develop' || github.event.merge_group.base_ref == 'refs/heads/develop' }}
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          # The check needs the full history of the release and staging branches.
-          fetch-depth: 0
-          persist-credentials: false
-      - name: Check for copied release commits
-        if: ${{ github.event_name == 'pull_request' }}
-        env:
-          BASE: ${{ github.event.pull_request.base.sha }}
-          HEAD: ${{ github.event.pull_request.head.sha }}
-        run: .github/scripts/releasing/check-no-copied-release-commits.sh "${BASE}" "${HEAD}"
-      # Runs even if the previous check fails, so that both problems are reported at once.
-      - name: Check merge-back has no new commits
-        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
-        env:
-          BASE: ${{ github.event.pull_request.base.sha }}
-          HEAD: ${{ github.event.pull_request.head.sha }}
-        run: .github/scripts/releasing/check-merge-back-commits.sh "${BASE}" "${HEAD}"
-      # The queue squashes PRs, so check the PR's own branch, named in the queue branch.
-      - name: Check the merge queue doesn't merge a release back
-        if: ${{ github.event_name == 'merge_group' }}
-        env:
-          BASE: ${{ github.event.merge_group.base_sha }}
-          HEAD_REF: ${{ github.event.merge_group.head_ref }}
-        run: |
-          if ! [[ "${HEAD_REF}" =~ /pr-([0-9]+)-[0-9a-f]+$ ]]; then
-              echo "Error: Can't find the PR number in '${HEAD_REF}'."
-              exit 1
-          fi
-          git fetch --no-tags origin "refs/pull/${BASH_REMATCH[1]}/head"
-          .github/scripts/releasing/check-no-merge-back.sh "${BASE}" FETCH_HEAD
-
   clang-tidy:
     needs: should-run
     if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -232,12 +184,6 @@ jobs:
     # 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
-    with:
-      # A pull request builds packages to prove they still build, and publishes
-      # nothing. Stated rather than left to the input's default, so that changing
-      # that default cannot start publishing from pull requests. No secrets are
-      # passed either, which is the second reason a publish here cannot succeed.
-      publish: false
 
   upload-recipe:
     needs:
@@ -272,7 +218,6 @@ jobs:
       - check-autogen
       - check-levelization
       - check-rename
-      - check-release-commits
       - clang-tidy
       - build-test
       - rust

.github/workflows/on-tag.yml

@@ -1,12 +1,5 @@
-# When a versioned tag is pushed, this workflow:
-#
-#   - builds and tests the release binaries
-#   - uploads the libxrpl recipe to the Conan remote
-#   - builds the DEB and RPM packages
-#   - publishes those packages to the XRPLF package repositories
-#
-# Nothing is published unless the build passes, which is also where CMake
-# rejects a tag that is not a valid version, e.g. 3.2.01.
+# This workflow uploads the libxrpl recipe to the Conan remote and builds
+# release packages when a versioned tag is pushed.
 name: Tag
 
 on:
@@ -25,14 +18,13 @@ defaults:
 jobs:
   upload-recipe:
     if: ${{ github.repository == 'XRPLF/rippled' }}
-    needs: build-test
     uses: ./.github/workflows/reusable-upload-recipe.yml
     secrets:
       remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
       remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
 
   build-test:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     uses: ./.github/workflows/reusable-build-test.yml
     strategy:
       fail-fast: true
@@ -45,16 +37,6 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   package:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      publish: true
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}
-      dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
-      antithesis_docker_host: ${{ secrets.ANTITHESIS_DOCKER_HOST }}
-      antithesis_docker_path: ${{ secrets.ANTITHESIS_DOCKER_PATH }}
-      antithesis_docker_credentials: ${{ secrets.ANTITHESIS_DOCKER_CREDENTIALS }}

.github/workflows/on-trigger.yml

@@ -15,15 +15,13 @@ on:
 
       # Keep the paths below in sync with those in `on-pr.yml`.
       - ".github/actions/build-deps/**"
-      - ".github/actions/release-info/**"
+      - ".github/actions/generate-version/**"
       - ".github/actions/setup-conan/**"
-      - ".github/actions/setup-nix-env/**"
       - ".github/scripts/strategy-matrix/**"
       - ".github/workflows/reusable-build-test-config.yml"
       - ".github/workflows/reusable-build-test.yml"
       - ".github/workflows/reusable-check-autogen.yml"
       - ".github/workflows/reusable-clang-tidy.yml"
-      - ".github/workflows/reusable-package-test-install.yml"
       - ".github/workflows/reusable-package.yml"
       - ".github/workflows/reusable-rust.yml"
       - ".github/workflows/reusable-strategy-matrix.yml"
@@ -31,7 +29,6 @@ on:
       - ".github/workflows/reusable-upload-recipe.yml"
       - ".clang-tidy"
       - ".codecov.yml"
-      - "bin/check-nix-store-refs.sh"
       - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "cfg/**"
@@ -45,9 +42,6 @@ on:
       - "CMakeLists.txt"
       - "conanfile.py"
       - "conan.lock"
-      - "flake.lock"
-      - "flake.nix"
-      - "nix/**"
       - "LICENSE.md"
       - "package/**"
       - "README.md"
@@ -121,15 +115,3 @@ jobs:
   package:
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      # Packages are built on every trigger; only develop pushes in XRPLF/rippled
-      # publish them, matching upload-recipe above.
-      publish: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}
-      dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
-      antithesis_docker_host: ${{ secrets.ANTITHESIS_DOCKER_HOST }}
-      antithesis_docker_path: ${{ secrets.ANTITHESIS_DOCKER_PATH }}
-      antithesis_docker_credentials: ${{ secrets.ANTITHESIS_DOCKER_CREDENTIALS }}

.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@279ec358f4a1be4088be3e024b07916fa97c75b6
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@3ba08d6ddf114092891d48491fc2e26c3ba15552
     with:
       runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-473fe44" }'
+      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-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
@@ -91,4 +91,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

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

@@ -69,12 +69,6 @@ on:
         type: string
         default: ""
 
-      toolchain:
-        description: 'Where the toolchain comes from ("nix" to build the flake CI environment on the runner, empty for the system one). macOS only: Linux always builds in a Nix image, and Nix has no Windows support.'
-        required: false
-        type: string
-        default: ""
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -117,9 +111,6 @@ jobs:
       VOIDSTAR_ENABLED: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
       VALIDATOR_KEYS_ENABLED: ${{ contains(inputs.cmake_args, '-Dvalidator_keys=ON') }}
       SANITIZERS_ENABLED: ${{ inputs.sanitizers != '' }}
-      # The binaries reusable-package.yml consumes. A private repository skips
-      # them except on a tag push, which is what produces its release packages.
-      PACKAGING_ARTIFACTS_ENABLED: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
@@ -129,15 +120,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: ${{ inputs.ccache_enabled }}
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ inputs.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Set ccache log file
         if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
         run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >>"${GITHUB_ENV}"
@@ -162,21 +148,7 @@ jobs:
         with:
           compiler: ${{ inputs.compiler }}
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          key: ${{ inputs.config_name }}
-          # two workspaces here because build artifacts are located in 2 places:
-          # - crates/target when cargo is called directly
-          # - build/cargo when cargo is called by cmake
-          workspaces: |
-            crates
-            crates -> ${{ runner.os == 'Windows' && format('../{0}/x64/{1}/cargo', env.BUILD_DIR, inputs.build_type) || format('../{0}/cargo', env.BUILD_DIR) }}
-
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ inputs.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ inputs.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -196,19 +168,6 @@ jobs:
         env:
           BUILD_TYPE: ${{ inputs.build_type }}
           CMAKE_ARGS: ${{ inputs.cmake_args }}
-          # GitHub creates a merge commit for a PR
-          # https://www.kenmuse.com/blog/the-many-shas-of-a-github-pull-request/
-          #
-          # We:
-          # - explicitly provide branch name
-          # - use `github.event.pull_request.head.sha` to get the SHA of last commit in the PR branch
-          #
-          # This way it works both for PRs and pushes to branches.
-          GITHUB_BRANCH_NAME: "${{ github.head_ref || github.ref_name }}"
-          GITHUB_HEAD_SHA: "${{ github.event.pull_request.head.sha || github.sha }}"
-          #
-          # If tag is being pushed, we use that version.
-          FORCE_XRPLD_VERSION: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
         run: |
           cmake \
               -G '${{ runner.os == 'Windows' && 'Visual Studio 18 2026' || 'Ninja' }}' \
@@ -253,25 +212,6 @@ jobs:
               --target "${CMAKE_TARGET}" \
               2>&1 | tee "${GITHUB_WORKSPACE}/build.log"
 
-      # Nothing may reference the store, so whole trees are checked - the Conan
-      # cache included, since what it holds is what gets uploaded and reused.
-      - name: Check the build output for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${BUILD_DIR}"
-
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
-      # Only what PatchNixBinary.cmake retargets: the toolchain in the Linux
-      # images always references the store. Same condition it uses.
-      - name: Check for Nix store references (Linux)
-        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
-        run: |
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpld_tests"
-
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
         run: |
@@ -282,7 +222,7 @@ jobs:
           fi
 
       - name: Upload the binary (Linux)
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && runner.os == 'Linux' }}
+        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xrpld-${{ inputs.config_name }}
@@ -296,7 +236,7 @@ jobs:
         run: ./validator-keys --unittest
 
       - name: Upload the validator-keys binary
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
+        if: ${{ github.event.repository.visibility == 'public' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: validator-keys-${{ inputs.config_name }}
@@ -336,7 +276,7 @@ jobs:
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           ldd ./xrpld
-          if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+|libgcc)' | wc -l)" -eq 0 ]; then
+          if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+)' | wc -l)" -eq 0 ]; then
               echo 'The binary is statically linked.'
           else
               echo 'The binary is dynamically linked.'
@@ -349,12 +289,18 @@ jobs:
         run: |
           ./xrpld --version | grep libvoidstar
 
+      - name: Run Rust tests
+        if: ${{ !inputs.build_only }}
+        working-directory: crates
+        # `xrpl-wasm-vm-ffi` is left out on Windows: its tests link as an executable, and
+        # MSVC - unlike the Unix linkers - will not dead-strip the never-called cxx wrappers
+        # whose C++ shims only the CMake build defines. The other runners cover these tests.
+        run: cargo nextest run --workspace --all-features --locked --no-tests=warn ${{ runner.os == 'Windows' && '--exclude xrpl-wasm-vm-ffi' || '' }}
+
       - name: Run the separate tests
         if: ${{ !inputs.build_only }}
         working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
-        run: |
-          ./xrpl_tests
-          ./xrpld_tests
+        run: ./xrpl_tests
 
       - name: Run the embedded tests
         if: ${{ !inputs.build_only }}
@@ -385,11 +331,6 @@ jobs:
 
           LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"
 
-      - name: Run Rust tests
-        if: ${{ !inputs.build_only }}
-        working-directory: crates
-        run: cargo nextest run --workspace --all-features --locked --no-tests=warn
-
       # 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 there is nothing to gain from repeating it
@@ -455,7 +396,7 @@ jobs:
 
       - name: Upload coverage report
         if: ${{ github.repository_owner == 'XRPLF' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           disable_search: true
           disable_telem: true

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

@@ -51,6 +51,5 @@ jobs:
       config_name: ${{ matrix.config_name }}
       sanitizers: ${{ matrix.sanitizers }}
       compiler: ${{ matrix.compiler || '' }}
-      toolchain: ${{ matrix.toolchain || '' }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

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

@@ -27,14 +27,14 @@ jobs:
   determine-files:
     permissions:
       contents: read
-    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@70145243b905dc3e040a61d39c00e178cfb96f71
+    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@d041ac9f1fa9f07a4ba335eb4c1c82233fb3fef6
 
   run-clang-tidy:
     name: Run clang tidy
     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-060957e"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-fecfc0c"
     permissions:
       contents: read
       issues: write
@@ -43,7 +43,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
@@ -59,12 +59,6 @@ jobs:
         with:
           compiler: ${{ env.COMPILER }}
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          workspaces: crates -> ../${{ env.BUILD_DIR }}/cargo
-
       - name: Setup Conan
         uses: ./.github/actions/setup-conan
 
@@ -86,13 +80,19 @@ jobs:
               -Dwerr=ON \
               -Dxrpld=ON \
               -Dverify_headers=ON \
-              -Drust=ON \
               ..
 
-      - name: Build clang-tidy prerequisites
+      # clang-tidy needs headers generated from proto files
+      - name: Build libxrpl.libpb
         working-directory: ${{ env.BUILD_DIR }}
         run: |
-          ninja -j ${{ steps.nproc.outputs.nproc }} tidy_prerequisites
+          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl.libpb
+
+      # clang-tidy needs cxxbridge headers generated from Rust crates
+      - name: Build xrpl_crates
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl_crates
 
       - name: Run clang tidy
         id: run_clang_tidy

.github/workflows/reusable-package-test-install.yml

@@ -1,120 +0,0 @@
-# Install one package format on every distro family it targets, one job per
-# package name and image, and run the binaries there. Called once per format by
-# reusable-package.yml, which owns the names and the image lists.
-name: Install packages
-
-on:
-  workflow_call:
-    inputs:
-      package_type:
-        description: 'The package format to install ("deb" or "rpm").'
-        required: true
-        type: string
-      package_names:
-        description: "JSON array of package names built for this format."
-        required: true
-        type: string
-      images:
-        description: "JSON array of container images to install in."
-        required: true
-        type: string
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  PACKAGE_DIR: packages
-
-jobs:
-  install:
-    strategy:
-      fail-fast: false
-      matrix:
-        package_name: ${{ fromJson(inputs.package_names) }}
-        image: ${{ fromJson(inputs.images) }}
-    name: "${{ matrix.package_name }} on ${{ matrix.image }}"
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-    container: ${{ matrix.image }}
-    timeout-minutes: 5
-
-    steps:
-      # Every package lands in one directory; the step below picks its own,
-      # which keeps this independent of the artifact names.
-      - name: Download package artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: "*-pkg"
-          merge-multiple: true
-          path: ${{ env.PACKAGE_DIR }}
-
-      - name: Find the package
-        id: find
-        env:
-          PACKAGE_NAME: ${{ matrix.package_name }}
-          PACKAGE_TYPE: ${{ inputs.package_type }}
-        run: |
-          # The version follows the name, separated by '_' in a DEB and '-' in an
-          # RPM. Requiring a digit after it is what keeps 'xrpld' from picking up
-          # another package, such as 'xrpld-assert'.
-          pattern="${PACKAGE_NAME}[_-][0-9]*.${PACKAGE_TYPE}"
-          package="$(find "${PACKAGE_DIR}" -type f -name "${pattern}" -print -quit)"
-          test -n "${package}" || {
-              echo "no ${pattern} found in ${PACKAGE_DIR}" >&2
-              exit 1
-          }
-          echo "package=${package}" >>"${GITHUB_OUTPUT}"
-
-      # Debian 11 went end-of-life on 2026-08-31
-      # (https://www.debian.org/News/2026/20260831) and its packages are
-      # already partly gone from deb.debian.org, so switch to the
-      # snapshot.debian.org entries the image ships commented out in its
-      # sources.list: they are pinned to the snapshot the image was built
-      # from, so they serve every version it needs and never go away.
-      # Snapshots keep their original, long-passed Valid-Until, hence the
-      # disabled check; the retries absorb snapshot.debian.org's throttling.
-      - name: Switch Debian 11 to snapshot.debian.org
-        if: ${{ matrix.image == 'debian:11' }}
-        run: |
-          sed -i 's|^deb |# deb |; s|^# deb http://snapshot|deb http://snapshot|' /etc/apt/sources.list
-          printf '%s\n' \
-              'Acquire::Check-Valid-Until "false";' \
-              'Acquire::Retries "3";' \
-              >/etc/apt/apt.conf.d/99snapshot
-
-      - name: Install the DEB
-        if: ${{ inputs.package_type == 'deb' }}
-        env:
-          DEBIAN_FRONTEND: noninteractive
-          PACKAGE: ${{ steps.find.outputs.package }}
-        run: |
-          # Stock Debian and Ubuntu images carry no package lists, so apt has
-          # nothing to resolve the systemd dependency from until it fetches them.
-          apt-get update -qq
-          apt-get install -y "./${PACKAGE}"
-
-      - name: Install the RPM
-        if: ${{ inputs.package_type == 'rpm' }}
-        env:
-          PACKAGE: ${{ steps.find.outputs.package }}
-        run: dnf install -y "./${PACKAGE}"
-
-      - name: Run xrpld
-        run: xrpld --version
-
-      - name: Run validator-keys
-        run: validator-keys --version
-
-      - name: Run rippled, the legacy compatibility symlink
-        run: rippled --version
-
-      - name: Check the service account
-        run: id xrpld
-
-      - name: Check the state directory
-        run: test -d /var/lib/xrpld
-
-      - name: Check the log directory
-        run: test -d /var/log/xrpld

.github/workflows/reusable-package.yml

@@ -1,57 +1,17 @@
-# Build, verify and publish Linux packages from the pre-built xrpld and
-# validator-keys artifacts, in these stages:
-#
-#   - 'package' builds and signs one format per config that carries a "package"
-#     map in linux.json; that map names the container image and the format
-#   - 'test-install-deb' and 'test-install-rpm' call
-#     reusable-package-test-install.yml to install what was built on a range of
-#     distros and run the binaries there, so a package that cannot be installed
-#     never reaches Nexus
-#   - 'publish' uploads with the image's publish_pkg.py, doing a --dry-run
-#     unless 'publish: true'
-#   - 'docker' builds an Ubuntu image from the tested DEB, and one with the
-#     voidstar binary for Antithesis, pushing them to Docker Hub and to the
-#     Antithesis registry only with 'publish: true'
-#
-# Only linux/amd64 is supported; the runner is hardcoded in the jobs below.
+# Build Linux packages (DEB and RPM) from pre-built binary artifacts (xrpld and
+# validator-keys). Discovers which configurations to package from linux.json
+# (configs in "package_configs") and fans out one job per distro. Only
+# linux/amd64 is supported; the runner is hardcoded in the job below.
 name: Package
 
 on:
   workflow_call:
     inputs:
-      publish:
-        description: "Whether to publish the packages after building them."
-        required: false
-        type: boolean
-        default: false
-      nexus_url:
-        description: "The base URL of the Nexus instance hosting the deb and rpm repositories."
+      pkg_release:
+        description: "Package release number. Increment when repackaging the same executable."
         required: false
         type: string
-        default: https://packages-upload.xrplf.org
-
-    secrets:
-      remote_username:
-        description: "The username of a Nexus account with write access to the repositories."
-        required: false
-      remote_password:
-        description: "The password or token for that Nexus account."
-        required: false
-      signing_key:
-        description: "Armoured PGP private key used to sign the RPMs."
-        required: false
-      dockerhub_token:
-        description: "A Docker Hub organization access token for xrplf, with push access to xrplf/xrpld."
-        required: false
-      antithesis_docker_host:
-        description: "The host of the Antithesis container registry, e.g. us-central1-docker.pkg.dev."
-        required: false
-      antithesis_docker_path:
-        description: "The repository path in that registry, the image name excluded."
-        required: false
-      antithesis_docker_credentials:
-        description: "The JSON key of a service account with push access to that repository."
-        required: false
+        default: "1"
 
 defaults:
   run:
@@ -59,15 +19,12 @@ defaults:
 
 env:
   BUILD_DIR: build
-  PACKAGE_DIR: packages
 
 jobs:
   generate-matrix:
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.generate.outputs.matrix }}
-      deb_package_names: ${{ steps.generate.outputs.deb_package_names }}
-      rpm_package_names: ${{ steps.generate.outputs.rpm_package_names }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -84,7 +41,7 @@ jobs:
 
   package:
     needs: [generate-matrix]
-    if: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
+    if: ${{ github.event.repository.visibility == 'public' }}
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
@@ -93,17 +50,12 @@ jobs:
       contents: read
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
     container: ${{ matrix.image }}
-    timeout-minutes: 10
+    timeout-minutes: 30
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
       - name: Download pre-built xrpld binary
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
@@ -119,230 +71,17 @@ jobs:
       - name: Make binaries executable
         run: chmod +x "${BUILD_DIR}/xrpld" "${BUILD_DIR}/validator-keys"
 
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
-
       - name: Build package
         env:
-          PACKAGE_TYPE: ${{ matrix.package_type }}
-          PACKAGE_VARIANT: ${{ matrix.package_variant }}
-          PKG_RELEASE: ${{ steps.release_info.outputs.pkg_release }}
-          CHANNEL: ${{ steps.release_info.outputs.channel }}
-        run: |
-          ./package/build_pkg.py \
-              --package-type "${PACKAGE_TYPE}" \
-              --build-dir "${BUILD_DIR}" \
-              --pkg-release "${PKG_RELEASE}" \
-              --variant "${PACKAGE_VARIANT}" \
-              --channel "${CHANNEL}"
+          PKG_RELEASE: ${{ inputs.pkg_release }}
+        run: ./package/build_pkg.sh
 
-      # Before the upload, so the artifact, the tested package and the published
-      # package are the same bytes.
-      - name: Sign RPM
-        if: ${{ inputs.publish && matrix.package_type == 'rpm' }}
-        env:
-          PKG_SIGNING_KEY: ${{ secrets.signing_key }}
-        run: ./package/sign_rpm.py --package-dir "${BUILD_DIR}"
-
-      # Split from the debug symbols, which are an order of magnitude larger, so
-      # that test-install downloads only what it installs. In the globs below the
-      # version follows the name, separated by '_' in a DEB and '-' in an RPM. A
-      # version starts with a digit and a longer name does not, so that one digit
-      # is what tells 'xrpld-3.4.1-...' from 'xrpld-assert-3.4.1-...'.
       - name: Upload package artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: ${{ matrix.xrpld_artifact_name }}-pkg
           path: |
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}_[0-9]*.deb
-            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-[0-9]*.rpm
+            ${{ env.BUILD_DIR }}/debbuild/*.deb
+            ${{ env.BUILD_DIR }}/debbuild/*.ddeb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/*.rpm
           if-no-files-found: error
-
-      - name: Upload debug symbol artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ${{ matrix.xrpld_artifact_name }}-pkg-debug
-          path: |
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.deb
-            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.ddeb
-            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-debuginfo-[0-9]*.rpm
-          if-no-files-found: error
-
-  # One call per format, so a variant packaged for one format is installed for
-  # that format alone. The images are every distro family that format targets,
-  # oldest release first, so both ends of the dependency range the packages
-  # declare are exercised.
-  test-install-deb:
-    needs: [generate-matrix, package]
-    name: install deb
-    uses: ./.github/workflows/reusable-package-test-install.yml
-    with:
-      package_type: deb
-      package_names: ${{ needs.generate-matrix.outputs.deb_package_names }}
-      images: |
-        [
-          "debian:11",
-          "debian:12",
-          "debian:13",
-          "ubuntu:20.04",
-          "ubuntu:22.04",
-          "ubuntu:24.04",
-          "ubuntu:26.04"
-        ]
-
-  test-install-rpm:
-    needs: [generate-matrix, package]
-    name: install rpm
-    uses: ./.github/workflows/reusable-package-test-install.yml
-    with:
-      package_type: rpm
-      package_names: ${{ needs.generate-matrix.outputs.rpm_package_names }}
-      images: |
-        [
-          "almalinux:9",
-          "almalinux:10",
-          "rockylinux/rockylinux:9",
-          "rockylinux/rockylinux:10",
-          "registry.access.redhat.com/ubi9/ubi",
-          "registry.access.redhat.com/ubi10/ubi"
-        ]
-
-  publish:
-    needs: [generate-matrix, package, test-install-deb, test-install-rpm]
-    strategy:
-      fail-fast: false
-      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-    name: "publish ${{ matrix.xrpld_artifact_name }}${{ !inputs.publish && ' (dry run)' || '' }}"
-    permissions:
-      contents: read
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: ${{ matrix.image }}
-    timeout-minutes: 30
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
-      # Both artifacts, so the debug symbols are published alongside the package.
-      - name: Download package artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: ${{ matrix.xrpld_artifact_name }}-pkg*
-          merge-multiple: true
-          path: ${{ env.PACKAGE_DIR }}
-
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
-
-      - name: Publish package
-        env:
-          CHANNEL: ${{ steps.release_info.outputs.channel }}
-          DRY_RUN_OPTION: ${{ !inputs.publish && '--dry-run' || '' }}
-          NEXUS_URL: ${{ inputs.nexus_url }}
-          NEXUS_USERNAME: ${{ inputs.publish && secrets.remote_username || '' }}
-          NEXUS_PASSWORD: ${{ inputs.publish && secrets.remote_password || '' }}
-        run: |
-          publish_pkg.py \
-              --channel "${CHANNEL}" \
-              --package-dir "${PACKAGE_DIR}" \
-              --nexus-url "${NEXUS_URL}" \
-              ${DRY_RUN_OPTION}
-
-  docker:
-    needs: [test-install-deb, test-install-rpm]
-    strategy:
-      fail-fast: false
-      matrix:
-        target: [xrpld, voidstar]
-    name: "docker ${{ matrix.target }}${{ !inputs.publish && ' (dry run)' || '' }}"
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    env:
-      CONTEXT: image-context
-      IMAGE: ${{ matrix.target == 'voidstar' && 'xrpld-voidstar' || 'xrplf/xrpld' }}:${{ github.ref_type == 'tag' && github.ref_name || 'develop' }}
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
-
-      # Docker Hub is public, so it only gets builds whose packages are public:
-      # those of a public codebase, and stable releases.
-      # The Antithesis registry is private, so it gets every build.
-      - name: Decide whether to push
-        env:
-          PUSH: ${{ inputs.publish && (matrix.target == 'voidstar' || github.event.repository.visibility == 'public' || steps.release_info.outputs.channel == 'stable') }}
-        run: echo "PUSH=${PUSH}" | tee -a "${GITHUB_ENV}"
-
-      - name: Download package artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: "*-pkg"
-          merge-multiple: true
-          path: ${{ env.PACKAGE_DIR }}
-
-      - name: Download voidstar binary
-        if: ${{ matrix.target == 'voidstar' }}
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: xrpld-ubuntu-clang-debug-amd64-voidstar
-          path: ${{ env.CONTEXT }}
-
-      - name: Build image
-        env:
-          TARGET: ${{ matrix.target }}
-        run: |
-          mkdir -p "${CONTEXT}"
-          find "${PACKAGE_DIR}" -type f -name 'xrpld_[0-9]*.deb' -exec cp {} "${CONTEXT}/" \;
-          docker build --pull --file package/images/xrpld/Dockerfile --target "${TARGET}" --tag "${IMAGE}" "${CONTEXT}"
-
-      - name: Start the server
-        run: |
-          container="$(docker run --detach "${IMAGE}" --standalone --silent --conf /etc/xrpld/xrpld.cfg)"
-          trap 'docker rm --force "${container}" >/dev/null' EXIT
-
-          for _ in $(seq 30); do
-              output="$(docker exec "${container}" xrpld --conf /etc/xrpld/xrpld.cfg server_info || true)"
-              if [[ "${output}" == *'"status" : "success"'* ]]; then
-                  exit 0
-              fi
-              sleep 2
-          done
-
-          docker logs "${container}"
-          exit 1
-
-      - name: Log in to Docker Hub
-        if: ${{ env.PUSH == 'true' && matrix.target == 'xrpld' }}
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
-        with:
-          username: xrplf
-          password: ${{ secrets.dockerhub_token }}
-
-      - name: Log in to the Antithesis registry
-        if: ${{ env.PUSH == 'true' && matrix.target == 'voidstar' }}
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
-        with:
-          registry: ${{ secrets.antithesis_docker_host }}
-          username: _json_key
-          password: ${{ secrets.antithesis_docker_credentials }}
-
-      - name: Push image
-        if: ${{ env.PUSH == 'true' }}
-        env:
-          REGISTRY: ${{ matrix.target == 'voidstar' && format('{0}/{1}/', secrets.antithesis_docker_host, secrets.antithesis_docker_path) || '' }}
-        run: |
-          docker tag "${IMAGE}" "${REGISTRY}${IMAGE}"
-          docker push "${REGISTRY}${IMAGE}"

.github/workflows/reusable-rust.yml

@@ -1,9 +1,8 @@
 # Clippy, coverage and documentation for the Rust crates in crates/. Each runs
 # as an independent job on a GitHub-hosted runner, but inside the same container
 # image used to build the crates in the C++/Corrosion path, so the toolchain
-# (and therefore the lints and the cargo cache) matches what production builds
-# use. Coverage is the exception: it needs the nightly rustc that honours
-# #[coverage(off)], which the image carries alongside the pinned stable.
+# (and therefore the lints, coverage instrumentation and the cargo cache) matches
+# what production builds use.
 #
 # Rust unit tests are deliberately NOT run here. They run as part of the C++
 # build (reusable-build-test-config.yml), which already compiles the crates on a
@@ -15,7 +14,7 @@ on:
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
-        required: true
+        required: false
 
 defaults:
   run:
@@ -28,36 +27,37 @@ permissions:
 jobs:
   clippy:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: crates
 
       - name: Run clippy
         run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
 
   coverage:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use the nightly Rust toolchain
-        run: rust-nightly path >>"${GITHUB_PATH}"
-
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: crates
 
       - name: Generate coverage report
         run: cargo llvm-cov nextest --workspace --all-features --locked --no-tests=warn --lcov --output-path lcov.info
 
       - name: Upload coverage report
         if: ${{ github.repository == 'XRPLF/rippled' }}
-        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           disable_search: true
           disable_telem: true
@@ -70,13 +70,15 @@ jobs:
 
   doc:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use cargo artifacts cache
-        uses: ./.github/actions/cargo-cache
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: crates
 
       - name: Build documentation
         env:

.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-060957e
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     env:
       REMOTE_NAME: ${{ inputs.remote_name }}
       CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
@@ -49,14 +49,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
-        with:
-          enable_ccache: false
-
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
+      - name: Generate build version number
+        id: version
+        uses: ./.github/actions/generate-version
 
       - name: Set up Conan
         uses: ./.github/actions/setup-conan
@@ -68,17 +63,33 @@ jobs:
         run: conan remote login "${REMOTE_NAME}" "${CONAN_LOGIN_USERNAME_XRPLF}" --password "${CONAN_PASSWORD_XRPLF}"
 
       - name: Upload Conan recipe (version)
-        env:
-          VERSION: ${{ steps.release_info.outputs.version }}
         run: |
-          conan export . --version="${VERSION}"
-          conan upload --confirm --check --remote="${REMOTE_NAME}" "xrpl/${VERSION}"
+          conan export . --version=${{ steps.version.outputs.version }}
+          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.version.outputs.version }}
 
+      # When this workflow is triggered by a push event, it will always be when merging into the
+      # 'develop' branch, see on-trigger.yml.
       - name: Upload Conan recipe (develop)
-        if: ${{ github.ref == 'refs/heads/develop' }}
+        if: ${{ github.event_name == 'push' }}
         run: |
           conan export . --version=develop
           conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/develop
 
+      # When this workflow is triggered by a pull request event, it will always be when merging into
+      # one of the 'release' branches, see on-pr.yml.
+      - name: Upload Conan recipe (rc)
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          conan export . --version=rc
+          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/rc
+
+      # When this workflow is triggered by a push event, it will always be when tagging a final
+      # release, see on-tag.yml.
+      - name: Upload Conan recipe (release)
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        run: |
+          conan export . --version=release
+          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/release
+
     outputs:
-      ref: xrpl/${{ steps.release_info.outputs.version }}
+      ref: xrpl/${{ steps.version.outputs.version }}

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

@@ -68,15 +68,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@b3e255d74d785d053e4903da8ac90983cd7d9e82
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ matrix.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Print build environment
         uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
 
@@ -92,9 +87,7 @@ jobs:
         with:
           compiler: ${{ matrix.compiler }}
 
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ matrix.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ matrix.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -113,10 +106,6 @@ jobs:
           log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
           sanitizers: ${{ matrix.sanitizers }}
 
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ matrix.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
       - name: Log into Conan remote
         if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
         run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.NEXUS_REMOTE_USERNAME }}" --password "${{ secrets.NEXUS_REMOTE_PASSWORD }}"

.gitignore

@@ -72,16 +72,11 @@ DerivedData
 /.zed/
 
 # AI tools.
-# Shared/committable AI agent config (AGENTS.md, CLAUDE.md, GEMINI.md, .claude/settings.json,
-# tool-specific rules files, etc.) should be checked in — see CONTRIBUTING.md. Only the
-# personal/local variants below are ignored.
 /.agent
 /.agents
 /.augment
-/.claude/settings.local.json
-AGENTS.override.md
-CLAUDE.local.md
-GEMINI.local.md
+/.claude
+/CLAUDE.md
 
 # Python
 __pycache__
@@ -92,9 +87,6 @@ target/
 # Direnv's directory
 /.direnv
 
-# Direnv's local, per-developer overrides
-/.envrc.local
-
 # clangd cache
 /.cache
 

.pre-commit-config.yaml

@@ -53,14 +53,9 @@ repos:
         entry: ./bin/pre-commit/check_doxygen_style.py
         language: python
         types_or: [c++, c]
-      - id: fix-gtest-names
-        name: "fix gtest names: CamelCase suite, snake_case test case"
-        entry: ./bin/pre-commit/fix_gtest_names.py
-        language: python
-        types_or: [c++, c]
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: e2b496dc2bd8340c2524cb9a2d2a943cde1bb6df # frozen: v23.1.1
+    rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
     hooks:
       - id: clang-format
         args: [--style=file]
@@ -75,46 +70,25 @@ repos:
         language: system
         types: [rust]
         pass_filenames: false # rustfmt formats the whole workspace
-      - id: check-coverage-attrs
-        name: check Rust coverage attributes
-        entry: ./bin/pre-commit/check_rust_coverage_attrs.py
-        language: python
-        files: ^crates/.*\.rs$
 
   - repo: https://github.com/BlankSpruce/gersemi-pre-commit
-    rev: f1c4833f8cf23c6d952673abc73525411a5719e8 # frozen: 0.29.1
+    rev: e98930bdc210d3387007f9252d8c1694ea7e410f # frozen: 0.27.7
     hooks:
       - id: gersemi
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: ef4a397f916211b4a39ccf9d3d9cbb6562157251 # frozen: v3.9.9
+    rev: 9337a74165b178ae2c766f60bee7252a0f06f3e8 # frozen: v3.9.5
     hooks:
       - id: prettier
         args: [--end-of-line=auto]
 
-  # Scoped to package/: the rest of the repo's Python has pre-existing findings,
-  # so widening these is its own change.
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: a56c0b927e6465d37cae3e97d35d4d18ab2b96cd # frozen: v0.16.9
-    hooks:
-      - id: ruff-check
-        args: [--fix]
-        files: ^package/.*\.py$
-
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 4160603246a6b365d4a2af661c6d71b0a0f50478 # frozen: 26.5.1
     hooks:
       - id: black
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 7ff8d35ae36a7d2b968f2f90b4c723e292e594ee # frozen: v2.3.1
-    hooks:
-      - id: mypy
-        args: [--strict]
-        files: ^package/.*\.py$
-
   - repo: https://github.com/scop/pre-commit-shfmt
-    rev: 479be5958357ba5ab65ce47172117348516860e9 # frozen: v3.14.1-1
+    rev: 05c1426671b9237fb5e1444dd63aa5731bec0dfb # frozen: v3.13.1-1
     hooks:
       - id: shfmt
         args: [--write, --indent=4, --case-indent=true]
@@ -133,7 +107,7 @@ repos:
         files: \.md$
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: f5c5d72342f35643988a9ffa0705c05bd3ff8383 # frozen: v10.3.0
+    rev: ea11f9efc0bec520073405bc30552da887ba71bc # frozen: v10.0.1
     hooks:
       - id: cspell
         name: check changed files spelling

AGENTS.md

@@ -1,42 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to AI coding agents (Claude Code, and other AGENTS.md-compatible tools) when working with code in this repository.
-
-## Build
-
-Required on Linux/macOS: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
-
-```bash
-nix develop
-```
-
-For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For the manual build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
-
-Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).
-
-## Testing
-
-Unit tests are a custom framework built into the `xrpld` binary itself (not Boost.Test/GTest/Catch); see [CONTRIBUTING.md](./CONTRIBUTING.md#unit-tests) for the basic invocation. Notes not covered there:
-
-- A suite's `--unittest` name is built from the arguments to its `BEAST_DEFINE_TESTSUITE`/`BEAST_DEFINE_TESTSUITE_PRIO` macro (usually at the bottom of the test file), in reverse order and joined with `.`: `BEAST_DEFINE_TESTSUITE(Credentials, app, xrpl)` → `xrpl.app.Credentials`.
-- `--unittest-arg` does nothing — don't use it.
-- Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
-- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
-
-## Lint/Format
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup and [CONTRIBUTING.md](./CONTRIBUTING.md#clang-tidy) for `clang-tidy` (opt-in, needs local `clang-tidy` and generated headers).
-
-## Code Style
-
-New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages).
-
-## Architecture
-
-Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
-
-- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`. Any change to transaction-processing behavior must be gated behind an Amendment.
-- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
-- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
-- `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
-- `crates/` — a Rust workspace (only built with `-Dxrpld -Drust=ON`) bridged into C++ via `cxxbridge`/the `cxx` crate; currently just a `hello_world` interop scaffold. Requires the Rust toolchain pinned in `rust-toolchain.toml` (the Nix devshell provides it automatically).

API-CHANGELOG.md

@@ -22,56 +22,17 @@ API version 2 is available in `xrpld` version 2.0.0 and later. See [API-VERSION-
 
 This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.
 
-## XRP Ledger server version 3.5.0
+## Unreleased
 
-Version 3.5.0 is not yet released.
+This section contains changes targeting a future version.
 
-### Additions in 3.5.0
+### Additions
 
-- `subscribe`, `unsubscribe`: Added an optional `mpt_issuances` request field, an array of MPT issuance IDs (hex strings). Subscribers receive a message with `type` `mptTransaction` for each validated transaction whose metadata affects a subscribed issuance; the message has the same fields as the `transactions` stream. MPT issuance subscriptions count toward the per-connection subscription limit. An empty array, a non-array value, or an invalid ID returns `invalidParams`. ([#5671](https://github.com/XRPLF/rippled/pull/5671))
-
-## XRP Ledger server version 3.4.0
-
-Version 3.4.0 is not yet released. These changes are available in the 3.4.0 beta releases.
-
-### Additions in 3.4.0
-
-- `ledger`: `nftoken_id`, `nftoken_ids`, and `offer_id` are now included in transaction metadata when transactions are expanded (`expand`, or admin-only `full`), matching the `tx`, `account_tx`, and `subscribe` (`transactions` stream) responses. ([#5706](https://github.com/XRPLF/rippled/pull/5706))
-
-### Bugfixes in 3.4.0
-
-- `sign`, `sign_for`, `submit`: `signature_target` now returns `invalidParams` unless it names `CounterpartySignature` or `SponsorSignature`. It previously accepted any inner object field, such as `Book` or `NFToken`, and signed into it.
-- `sign`, `sign_for`, `submit`, `submit_multisigned`: With `fixCleanup3_4_0` enabled, a signature in `CounterpartySignature` or `SponsorSignature` covers a different prefix than the transaction's own signature, so a signature can no longer be moved from one of those roles into another. Clients that build these signatures themselves must use the new prefixes: `CPT` and `CPM` (single- and multi-signing) for `CounterpartySignature`, and `SPN` and `SPM` for `SponsorSignature`.
-- `get_aggregate_price`: Duplicate entries in the `oracles` request array are now ignored. [#6586](https://github.com/XRPLF/rippled/pull/6586)
-- `vault_info`: Errors now identify what the request got wrong instead of reporting every failure as the unregistered token `malformedRequest`, and the `error`, `error_code` and `error_message` fields now agree with each other. An invalid `vault_id` or `seq` returns `invalidParams`, an invalid `owner` returns `actMalformed`, and a request that mixes `vault_id` with `owner`/`seq` or supplies neither returns `invalidParams` with a message naming the accepted combinations. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: A well-formed all-zero `vault_id` now returns `entryNotFound` instead of being rejected as malformed, and `entryNotFound` responses now include `error_code` and `error_message`. Clients that request `ripplerpc` 3.0 or above therefore receive HTTP 400 with that error rather than HTTP 200. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: `vault_id` and `owner` must now be strings, matching how `ledger_entry` reads the same fields. An object or an array in either field previously produced an internal error, and a number was silently converted to its decimal text; `vault_id` now returns `invalidParams` and `owner` returns `actMalformed`. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `gateway_balances`: The `account` and `ident` fields now return an `invalidParams` error if the value is not a string, instead of an `internal` error. [#7655](https://github.com/XRPLF/rippled/pull/7655)
-- `account_lines`: The `peer` field now returns an error if the value is not a string. [#7728](https://github.com/XRPLF/rippled/pull/7728)
-- `ledger`: `delivered_amount` is now included in the metadata of successful `AccountDelete` transactions when transactions are expanded (`expand`, or admin-only `full`). Previously it was only added for `Payment` and `CheckCash`, which made `ledger` inconsistent with `tx` and `account_tx`. [#5706](https://github.com/XRPLF/rippled/pull/5706)
-- `noripple_check`: The `transactions` field is no longer included in error responses; it is still returned (possibly as an empty array) whenever `transactions` is `true` and the request succeeds. A malformed `account` is now rejected before the ledger is looked up, so that error response no longer carries the `ledger_hash`, `ledger_index`, and `validated` fields ([#6303](https://github.com/XRPLF/rippled/pull/6303)).
-
-## XRP Ledger server version 3.3.0
-
-[Version 3.3.0](https://github.com/XRPLF/rippled/releases/tag/3.3.0) was released on Aug 6, 2026.
-
-### Additions in 3.3.0
-
-- `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. ([#6126](https://github.com/XRPLF/rippled/pull/6126))
-
-## XRP Ledger server version 3.2.1
-
-[Version 3.2.1](https://github.com/XRPLF/rippled/releases/tag/3.2.1) was released on Aug 1, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.2.0
-
-[Version 3.2.0](https://github.com/XRPLF/rippled/releases/tag/3.2.0) was released on Jun 16, 2026.
-
-### Additions in 3.2.0
+- `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)):
   - `TRANSACTION_FORMATS`: Describes the fields and their optionality for each transaction type, including common fields shared across all transactions.
   - `LEDGER_ENTRY_FORMATS`: Describes the fields and their optionality for each ledger entry type, including common fields shared across all ledger entries.
@@ -79,8 +40,9 @@ This release contains bug fixes only and no API changes.
   - `LEDGER_ENTRY_FLAGS`: Maps ledger entry type names to their flags and flag values.
   - `ACCOUNT_SET_FLAGS`: Maps AccountSet flag names (asf flags) to their numeric values.
 
-### Bugfixes in 3.2.0
+### Bugfixes
 
+- `get_aggregate_price`: Duplicate entries in the `oracles` request array are now ignored. [#6586](https://github.com/XRPLF/rippled/pull/6586)
 - Peer Crawler: The `port` field in `overlay.active[]` now consistently returns an integer instead of a string for outbound peers. [#6318](https://github.com/XRPLF/rippled/pull/6318)
 - `ping`: The `ip` field is no longer returned as an empty string for proxied connections without a forwarded-for header. It is now omitted, consistent with the behavior for identified connections. [#6730](https://github.com/XRPLF/rippled/pull/6730)
 - gRPC `GetLedgerDiff`: Fixed error message that incorrectly said "base ledger not validated" when the desired ledger was not validated. [#6730](https://github.com/XRPLF/rippled/pull/6730)
@@ -93,24 +55,6 @@ This release contains bug fixes only and no API changes.
 - `subscribe`: The `taker` field in the `books` array now returns `actMalformed` instead of `badIssuer` if the value is not a valid account. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 - Fixed a bug in `Forwarded` HTTP header parsing where the extracted IP address could be incorrect when no comma or semicolon delimiter follows the address. This could cause the server to misidentify a client's IP address when operating behind a reverse proxy. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 
-## XRP Ledger server version 3.1.3
-
-[Version 3.1.3](https://github.com/XRPLF/rippled/releases/tag/3.1.3) was released on May 8, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.1.2
-
-[Version 3.1.2](https://github.com/XRPLF/rippled/releases/tag/3.1.2) was released on Mar 12, 2026.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 3.1.1
-
-[Version 3.1.1](https://github.com/XRPLF/rippled/releases/tag/3.1.1) was released on Feb 23, 2026.
-
-This release contains bug fixes only and no API changes.
-
 ## XRP Ledger server version 3.1.0
 
 [Version 3.1.0](https://github.com/XRPLF/rippled/releases/tag/3.1.0) was released on Jan 27, 2026.

BUILD.md

@@ -4,14 +4,34 @@
 
 ## Minimum Requirements
 
-For the hardware needed to run a node, see
-[System Requirements](https://xrpl.org/system-requirements.html).
+See [System Requirements](https://xrpl.org/system-requirements.html).
 
-For the software needed to build xrpld, see the
-[environment setup guide](./docs/build/environment.md).
+Building xrpld generally requires Git, Python, Conan, CMake, and a C++
+compiler.
+
+- [Python](https://www.python.org/downloads/)
+- [Conan](https://conan.io/downloads.html)
+- [CMake](https://cmake.org/download/)
+
+You can verify that the required tools are installed and runnable with:
+
+```bash
+./bin/check-tools.sh
+```
+
+`xrpld` is written in the C++23 dialect. The [tested compiler versions][cpp23-support] are:
+
+| Compiler    | Version         |
+| ----------- | --------------- |
+| GCC         | 15.2            |
+| Clang       | 22              |
+| Apple Clang | 21              |
+| MSVC        | 19.44[^windows] |
 
 ## Operating Systems
 
+Please see the [environment setup guide](./docs/build/environment.md) for detailed instructions for all platforms.
+
 ### Linux
 
 The Ubuntu Linux distribution has received the highest level of quality
@@ -27,8 +47,9 @@ CI testing is done in macOS 26 (Tahoe), but the build defaults `CMAKE_OSX_DEPLOY
 
 ### Windows
 
-Windows is used by some engineers for development only, and is not recommended
-for production use.
+Windows is used by some engineers for development only.
+
+[^windows]: Windows is not recommended for production use.
 
 ## Steps
 
@@ -41,41 +62,49 @@ branch.
 git checkout develop
 ```
 
-For a release or release candidate, check out its [tag](https://github.com/XRPLF/rippled/releases), e.g.:
+For a release candidate, choose the relevant release branch, e.g.
+`release/3.2.x`.
 
 ```bash
-git checkout 3.4.0
+git checkout release/3.2.x
 ```
 
-See [RELEASING.md](./RELEASING.md) for how branches and releases are organized.
-
-A build reports `0.0.0-dev` with its short commit hash as build metadata, e.g.
-`0.0.0-dev+0123abc`. Only builds of a release, from a tag in CI or a versioned
-Conan reference, report a release version. To use another version, set the
-`FORCE_XRPLD_VERSION` environment variable when running CMake, e.g.
-`FORCE_XRPLD_VERSION=3.4.0`.
+For a stable release, choose one of the [tagged
+releases](https://github.com/XRPLF/rippled/releases).
 
 ### Set Up Conan
 
-Once your [development environment](./docs/build/environment.md) is ready, set
-Conan up for this repository:
+After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python,
+Conan, CMake, and a C++ compiler, you may need to set up your Conan profile.
+
+These instructions assume a basic familiarity with Conan and CMake. If you are
+unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official
+[Getting Started][conan-getting-started] walkthrough.
+
+#### Profiles
+
+We recommend that you install our Conan profiles:
 
 ```bash
-./conan/init.sh
+conan config install conan/profiles/ -tf $(conan config home)/profiles/
 ```
 
-That installs our [`global.conf`](./conan/global.conf), our Conan
-[profiles](./conan/profiles), and the `xrplf` remote that hosts some of our
-dependencies. It honours `CONAN_HOME` and never deletes an existing Conan home,
-so it is safe to re-run — it only overwrites the files it manages.
+You can check your Conan profile by running:
 
-> [!TIP]
-> In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is
-> already done for you: the script runs on entry.
+```bash
+conan profile show
+```
 
-You can inspect the resulting profile with `conan profile show`. If it is not
-suitable for your environment, create a custom profile and pass it to Conan — see
-[Advanced Conan configuration](./docs/build/advanced_conan.md).
+If the default profile is not suitable for your environment, you can create a custom profile and pass it to Conan.
+More information on customizing Conan can be found in the [Advanced Conan configuration](./docs/build/advanced_conan.md).
+
+#### Add xrplf remote
+
+Run the following command to add the `xrplf` remote, which hosts some of our dependencies:
+
+```bash
+conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/
+```
 
 ### Set Up Ccache
 
@@ -240,14 +269,10 @@ which is only enabled when the `coverage` option is set, e.g. with
 Prerequisites for the coverage report:
 
 - [gcovr tool][gcovr] (can be installed e.g. with [pip][python-pip])
-- `gcov` for GCC or `llvm-cov` for Clang, usually installed with the compiler
+- `gcov` for GCC (installed with the compiler by default) or
+- `llvm-cov` for Clang (installed with the compiler by default)
 - `Debug` build type
 
-> [!NOTE]
-> Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell):
-> its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`,
-> or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler.
-
 A coverage report is created when the following steps are completed, in order:
 
 1. `xrpld` binary built with instrumentation data, enabled by the `coverage`
@@ -308,7 +333,6 @@ See [Sanitizers docs](./docs/build/sanitizers.md) for more details.
 | ---------------- | ------------- | ----------------------------------------------------------------------------- |
 | `assert`         | OFF           | Force enabling assertions.                                                    |
 | `coverage`       | OFF           | Prepare the coverage report.                                                  |
-| `rust`           | OFF           | Build the Rust crates and the C++ code that depends on them.                  |
 | `tests`          | OFF           | Build tests.                                                                  |
 | `unity`          | OFF           | Configure a unity build.                                                      |
 | `verify_headers` | ON            | Make the `verify-headers` target available to compile each header on its own. |
@@ -321,30 +345,6 @@ memory) since they concatenate sources into fewer translation units. Non-unity
 builds may be faster for incremental builds, and can be helpful for detecting
 `#include` omissions.
 
-### Rust crates
-
-The Rust crates in `crates/` are only part of the build when `rust` is ON. With
-`-Drust=OFF` (the default) the `crates` directory is not added to the build, no
-cxxbridge bindings are generated, and the C++ tests that exercise the Rust
-interop are not compiled — so no Rust toolchain is needed. CI builds always pass
-`-Drust=ON`.
-
-With `-Drust=ON` you need one extra dependency: a Rust toolchain (`cargo`,
-`rustc`) matching the channel pinned in
-[`rust-toolchain.toml`](./rust-toolchain.toml), which compiles the crates and
-generates the cxxbridge bindings. It is provided by the
-[Nix development shell](./docs/build/nix.md), so `-Drust=ON` works there without
-any extra setup; otherwise install it as described in
-[Rust](./docs/build/environment.md#rust).
-
-The crates also have their own Rust unit tests. Those are run with `cargo` and
-need only the Rust toolchain, independently of CMake and of the `rust` option
-(CI runs them with `cargo nextest`):
-
-```bash
-cargo test --manifest-path crates/Cargo.toml --workspace
-```
-
 ### Verifying headers
 
 The regular build only compiles `.cpp` files, so a header is only ever checked
@@ -389,14 +389,10 @@ After any updates or changes to dependencies, you may need to do the following:
 4. [Regenerate lockfile](./docs/build/advanced_conan.md#conan-lockfile).
 5. Re-run [conan install](#build-and-test).
 
-If you are using the Nix development shell, whether prebuilt Conan binaries apply
-depends on your platform — see
-[Prebuilt packages](./docs/build/nix.md#prebuilt-packages).
-
 #### ERROR: Package not resolved
 
 If you're seeing an error like `ERROR: Package 'snappy/1.1.10' not resolved: Unable to find 'snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1756234314.246' in remotes.`,
-please [set Conan up](#set-up-conan) so the `xrplf` remote is configured, or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
+please [add `xrplf` remote](#add-xrplf-remote) or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
 
 ### `protobuf/port_def.inc` file not found
 
@@ -416,6 +412,7 @@ For example, if you want to build Debug:
 1. For conan install, pass `--settings build_type=Debug`
 2. For cmake, pass `-DCMAKE_BUILD_TYPE=Debug`
 
+[cpp23-support]: https://en.cppreference.com/w/cpp/compiler_support/23
 [conan-getting-started]: https://docs.conan.io/en/latest/getting_started.html
 [unity-build]: https://en.wikipedia.org/wiki/Unity_build
 [gcovr]: https://gcovr.com/en/stable/getting-started.html

CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

CMakeLists.txt

@@ -77,6 +77,7 @@ endif()
 include(PatchNixBinary)
 
 include(XrplSanity)
+include(XrplVersion)
 include(XrplSettings)
 # this check has to remain in the top-level cmake because of the early return statement
 if(packages_only)
@@ -114,7 +115,6 @@ find_package(secp256k1 REQUIRED)
 find_package(SOCI REQUIRED)
 find_package(SQLite3 REQUIRED)
 find_package(xxHash REQUIRED)
-find_package(xrpl-rpc-spec REQUIRED)
 
 target_link_libraries(
     xrpl_libs
@@ -158,13 +158,8 @@ if(coverage)
     include(XrplCov)
 endif()
 
-add_custom_target(tidy_prerequisites)
-
-if(rust)
-    add_subdirectory(crates)
-endif()
+add_subdirectory(crates)
 include(XrplCore)
-
 include(XrplProtocolAutogen)
 include(XrplInstall)
 include(XrplValidatorKeys)
@@ -175,7 +170,6 @@ include(XrplPackaging)
 if(tests)
     include(CTest)
     add_subdirectory(src/tests/libxrpl)
-    add_subdirectory(src/tests/xrpld)
 endif()
 
 if(benchmark)

CONTRIBUTING.md

@@ -14,13 +14,9 @@ The following branches exist in the main project repository:
 
 - `develop`: The latest set of unreleased features, and the most common
   starting point for contributions.
-- `staging/*` (e.g. `staging/3.4.x`): Staging branches, one per release line,
-  where fixes for that line are developed.
-- `release/*` (e.g. `release/3.4.x`): Release branches, one per release line,
-  holding the latest public release candidate or release for that line.
-  Releases are published as [tagged releases](https://github.com/XRPLF/rippled/releases).
-
-See [RELEASING.md](./RELEASING.md) for how these branches are used.
+- `release/*` (e.g. `release/3.2.x`): Release branches, one per release line,
+  holding the latest release candidate, or stable release for that line.
+  Stable releases are published as [tagged releases](https://github.com/XRPLF/rippled/releases).
 
 The tip of each branch must be signed. In order for GitHub to sign a
 squashed commit that it builds from your pull request, GitHub must know
@@ -63,17 +59,6 @@ to an existing XLS. Neither change will be released (in an amendment's
 case, marked as `Supported::yes`) until the corresponding XLS's status
 is `Final`.
 
-## AI coding agents
-
-[`AGENTS.md`](./AGENTS.md) (and its `CLAUDE.md` symlink, for Claude Code) holds shared, checked-in guidance for AI coding agents working in this repository — build/test/lint commands and architecture notes. Additional `AGENTS.md` files may exist in subdirectories to give agents context specific to that part of the codebase; whenever you add one, also add a `CLAUDE.md` symlink pointing to it (`ln -s AGENTS.md CLAUDE.md`) so Claude Code picks it up too.
-
-If you want to give an agent personal instructions that shouldn't be shared with other contributors (e.g. your own workflow preferences), those are gitignored, not checked in:
-
-- `CLAUDE.local.md` — read by Claude Code alongside `CLAUDE.md`.
-- `AGENTS.override.md` — read by AGENTS.md-compatible tools that support a personal override file layered on top of `AGENTS.md`.
-
-Likewise, `.claude/settings.local.json` is for personal, untracked Claude Code settings, while `.claude/settings.json` is shared.
-
 ## Before making a pull request
 
 (Or marking a draft pull request as ready.)
@@ -97,7 +82,7 @@ If you create new source files, they must be organized as follows:
   under `include/xrpl`, and source (`.cpp`) files must go under
   `src/libxrpl`.
 - All other non-test files must go under `src/xrpld`.
-- New test source files should use `gtest` and go under `src/tests`, unless that isn't possible, in which case they should use our legacy test framework and go under `src/test`.
+- 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 easiest
@@ -149,8 +134,8 @@ tl;dr
 
 In general, pull requests use `develop` as the base branch.
 
-The exceptions are fixes for an existing release line,
-which use that line's staging branch (e.g. `staging/3.4.x`) as the base.
+The exceptions are fixes, improvements, and hotfixes for an existing release,
+which use that release's branch (e.g. `release/3.2.x`) as the base.
 
 If your changes are not quite ready, but you want to make it easily available
 for preliminary examination or review, you can create a "Draft" pull request.
@@ -240,9 +225,8 @@ 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` and `cargo fmt` — run tools from your own environment; see
-[Installing clang-tidy](#installing-clang-tidy) and
-[Rust](./docs/build/environment.md#rust) for how to get those.
+`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:
 
@@ -271,7 +255,6 @@ The hooks configured in this repository include, among others:
 - `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
-- `cargo fmt` — Rust formatting for the crates in `crates/`
 - `prettier`, `black`, `shfmt` — formatting for JavaScript/JSON/Markdown, Python, and shell
 - `cspell` — spell checking
 
@@ -336,11 +319,7 @@ See the [environment setup guide](./docs/build/environment.md#clang-tidy) for ho
 
 ### Running clang-tidy locally
 
-Before running clang-tidy, you must generate the files it depends on (protobuf headers, and, when the project is configured with `-Drust=ON`, the cxxbridge headers from the Rust crates). Configure the project as described in [`BUILD.md`](./BUILD.md), then build the `tidy_prerequisites` target, which generates all of them:
-
-```bash
-cmake --build build --target tidy_prerequisites
-```
+Before running clang-tidy, you must build the project to generate required files (particularly protobuf headers). Refer to [`BUILD.md`](./BUILD.md) for build instructions.
 
 #### Via pre-commit (recommended)
 
@@ -483,12 +462,8 @@ exists, then no other unit test will be executed, apart from `TestSuiteName`.
     elsewhere in the codebase.
 12. Use clear and self-explanatory names for functions, variables,
     structs and classes.
-13. Use TitleCase for classes, structs, type aliases and filenames,
-    camelCase for function and variable names, lower case for namespaces and
-    folders. The exception is a type alias that generic code looks up by name
-    (`value_type`, `iterator`, `result_type`, and the rest of the standard
-    container, hash and clock members), which keeps its snake_case spelling;
-    `.clang-tidy` lists the names that are allowed.
+13. Use TitleCase for classes, structs and filenames, camelCase for
+    function and variable names, lower case for namespaces and folders.
 14. Provide as many comments as you feel that a competent programmer
     would need to understand what your code does.
 
@@ -595,16 +570,15 @@ the suggested commit message, or modify it as needed.
 
 #### Slightly more complicated pull requests
 
-Some pull requests need to be pushed to their base branch (usually `develop`)
-as more than one commit.
-A PR author may _request_ to merge as separate commits. They
+Some pull requests need to be pushed to `develop` as more than one
+commit. A PR author may _request_ to merge as separate commits. They
 must _justify_ why separate commits are needed, and _specify_ how they
 would like the commits to be merged. If you disagree with the author,
 discuss it with them directly.
 
 If the process is reasonable, follow it. The simplest option is to do a
-fast forward only merge (`--ff-only`) on the command line
-and push to the base branch.
+fast forward only merge (`--ff-only`) on the command line and push to
+`develop`.
 
 Some examples of when separate commits are worthwhile are:
 
@@ -617,10 +591,9 @@ Some examples of when separate commits are worthwhile are:
 
 Either way, check that:
 
-- The commits are based on the current tip of the base branch.
-- The commits are clean:
-  No merge commits (except when merging a release, see [RELEASING.md](./RELEASING.md)),
-  no "[FOLD]" or "fixup!" messages.
+- The commits are based on the current tip of `develop`.
+- The commits are clean: No merge commits (except when reverse
+  merging), no "[FOLD]" or "fixup!" messages.
 - All commits are signed. If the commits are not signed by the author, use
   `git commit --amend -S` to sign them yourself.
 - At least one (but preferably all) of the commits has the PR number
@@ -632,8 +605,578 @@ use them!**
 
 ### Releases
 
-Releases, release branches, and merging releases back into `develop`
-are described in [RELEASING.md](./RELEASING.md).
+All releases, including release candidates and betas, are handled
+differently from typical PRs. Most importantly, never use
+the Github UI to merge a release.
+
+Xrpld uses a linear workflow model that can be summarized as:
+
+1. In between releases, developers work against the `develop` branch.
+2. Periodically, a maintainer will build and tag a beta version from
+   `develop`, which is pushed to `release`.
+   - Betas are usually released every two to three weeks, though that
+     schedule can vary depending on progress, availability, and other
+     factors.
+3. When the changes in `develop` are considered stable and mature enough
+   to be ready to release, a release candidate (RC) is built and tagged
+   from `develop`, and merged to `release`.
+   - Further development for that release (primarily fixes) then
+     continues against `release`, while other development continues on
+     `develop`. Effectively, `release` is forked from `develop`. Changes
+     to `release` must be reverse merged to `develop`.
+4. When the candidate has passed testing and is ready for release, the
+   final release is merged to `master`.
+5. If any issues are found post-release, a hotfix / point release may be
+   created, which is merged to `master`, and then reverse merged to
+   `develop`.
+
+#### Betas, and the first release candidate
+
+##### Preparing the `develop` branch
+
+1. Optimally, the `develop` branch will be ready to go, with all
+   relevant PRs already merged.
+2. If there are any PRs pending, merge them **BEFORE** preparing the beta.
+   1. If only one or two PRs need to be merged, merge those PRs [as
+      normal](#when-and-how-to-merge-pull-requests), updating the second
+      one, and waiting for CI to finish in between.
+   2. If there are several pending PRs, do not use the Github UI,
+      because the delays waiting for CI in between each merge will be
+      unnecessarily onerous. (Incidentally, this process can also be
+      used to merge if the Github UI has issues.) Merge each PR branch
+      directly to a `release-next` on your local machine and create a single
+      PR, then push your branch to `develop`.
+      1. Squash the changes from each PR, one commit each (unless more
+         are needed), being sure to sign each commit and update the
+         commit message to include the PR number. You may be able to use
+         a fast-forward merge for the first PR.
+      2. Push your branch.
+      3. Continue to [Making the release](#making-the-release) to update
+         the version number, etc.
+
+      The workflow may look something like:
+
+```
+git fetch --multiple upstreams user1 user2 user3 [...]
+git checkout -B release-next --no-track upstream/develop
+
+# Only do an ff-only merge if pr-branch1 is either already
+# squashed, or needs to be merged with separate commits,
+# and has no merge commits.
+# Use -S on the ff-only merge if pr-branch1 isn't signed.
+git merge [-S] --ff-only user1/pr-branch1
+
+git merge --squash user2/pr-branch2
+git commit -S # Use the commit message provided on the PR
+
+git merge --squash user3/pr-branch3
+git commit -S # Use the commit message provided on the PR
+
+[...]
+
+# Make sure the commits look right
+git log --show-signature "upstream/develop..HEAD"
+
+git push --set-upstream origin
+
+# Continue to "Making the release" to update the version number, so
+# everything can be done in one PR.
+```
+
+You can also use the [squash-branches] script.
+
+You may also need to manually close the open PRs after the changes are
+merged to `develop`. Be sure to include the commit ID.
+
+##### Making the release
+
+This includes, betas, and the first release candidate (RC).
+
+1. If you didn't create one [preparing the `develop`
+   branch](#preparing-the-develop-branch), Ensure there is no old
+   `release-next` branch hanging around. Then make a `release-next`
+   branch that only changes the version number. e.g.
+
+```
+git fetch upstreams
+
+git checkout --no-track -B release-next upstream/develop
+
+v="A.B.C-bD"
+build=$( find -name BuildInfo.cpp )
+sed 's/\(^.*versionString =\).*$/\1 "'${v}'"/' ${build} > version.cpp && mv -vi version.cpp ${build}
+
+git diff
+
+git add ${build}
+
+git commit -S -m "Set version to ${v}"
+
+# You could use your "origin" repo, but some CI tests work better on upstream.
+git push upstream-push
+git fetch upstreams
+git branch --set-upstream-to=upstream/release-next
+```
+
+You can also use the [update-version] script. 2. Create a Pull Request for `release-next` with **`develop`** as
+the base branch.
+
+1.  Use the title "[TRIVIAL] Set version to X.X.X-bX".
+2.  Instead of the default description template, use the following:
+
+```
+## High Level Overview of Change
+
+This PR only changes the version number. It will be merged as
+soon as Github CI actions successfully complete.
+```
+
+3. Wait for CI to successfully complete, and get someone to approve
+   the PR. (It is safe to ignore known CI issues.)
+4. Push the updated `develop` branch using your `release-next`
+   branch. **Do not use the Github UI. It's important to preserve
+   commit IDs.**
+
+```
+git push upstream-push release-next:develop
+```
+
+5. In the unlikely event that the push fails because someone has merged
+   something else in the meantime, rebase your branch onto the updated
+   `develop` branch, push again, and go back to step 3.
+6. Ensure that your PR against `develop` is closed. Github should do it
+   automatically.
+7. Once this is done, forward progress on `develop` can continue
+   (other PRs may be merged).
+8. Now create a Pull Request for `release-next` with **`release`** as
+   the base branch. Instead of the default template, reuse and update
+   the message from the previous release. Include the following verbiage
+   somewhere in the description:
+
+```
+The base branch is `release`. [All releases (including
+betas)](https://github.com/XRPLF/rippled/blob/develop/CONTRIBUTING.md#before-you-start)
+go in `release`. This PR branch will be pushed directly to `release` (not
+squashed or rebased, and not using the GitHub UI).
+```
+
+7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
+   offline, but at least one approval will be needed on the PR.
+   - If issues are discovered during testing, simply abandon the
+     release. It's easy to start a new release, it should be easy to
+     abandon one. **DO NOT REUSE THE VERSION NUMBER.** e.g. If you
+     abandon 2.4.0-b1, the next attempt will be 2.4.0-b2.
+8. Once everything is ready to go, push to `release`.
+
+```
+git fetch upstreams
+
+# Just to be safe, do a dry run first:
+git push --dry-run upstream-push release-next:release
+
+# If everything looks right, push the branch
+git push upstream-push release-next:release
+
+# Check that all of the branches are updated
+git fetch upstreams
+git log -1 --oneline
+# The output should look like:
+# 0123456789 (HEAD -> upstream/release-next, upstream/release,
+#            upstream/develop) Set version to 2.4.0-b1
+# Note that upstream/develop may not be on this commit, but
+# upstream/release must be.
+# Other branches, including some from upstream-push, may also be
+# present.
+```
+
+9. Tag the release, too.
+
+```
+git tag <version number>
+git push upstream-push <version number>
+```
+
+10. Delete the `release-next` branch on the repo. Use the Github UI or:
+
+```
+git push --delete upstream-push release-next
+```
+
+11. Finally [create a new release on
+    Github](https://github.com/XRPLF/rippled/releases).
+
+#### Release candidates after the first
+
+Once the first release candidate is [merged into
+release](#making-the-release), then `release` and `develop` _are allowed
+to diverge_.
+
+If a bug or issue is discovered in a version that has a release
+candidate being tested, any fix and new version will need to be applied
+against `release`, then reverse-merged to `develop`. This helps keep git
+history as linear as possible.
+
+A `release-next` branch will be created from `release`, and any further
+work for that release must be based on `release-next`. Specifically,
+PRs must use `release-next` as the base, and those PRs will be merged
+directly to `release-next` when approved. Changes should be restricted
+to bug fixes, but other changes may be necessary from time to time.
+
+1. Open any PRs for the pending release using `release-next` as the base,
+   so they can be merged directly in to it. Unlike `develop`, though,
+   `release-next` can be thrown away and recreated if necessary.
+2. Once a new release candidate is ready, create a version commit as in
+   step 1 [above](#making-the-release) on `release-next`. You can use
+   the [update-version] script for this, too.
+3. Jump to step 8 ("Now create a Pull Request for `release-next` with
+   **`release`** as the base") from the process
+   [above](#making-the-release) to merge `release-next` into `release`.
+
+##### Follow up: reverse merge
+
+Once the RC is merged and tagged, it needs to be reverse merged into
+`develop` as soon as possible.
+
+1. Create a branch, based on `upstream/develop`.
+   The branch name is not important, but could include "mergeNNNrcN".
+   E.g. For release A.B.C-rcD, use `mergeABCrcD`.
+
+```
+git fetch upstreams
+
+git checkout --no-track -b mergeABCrcD upstream/develop
+```
+
+2. Merge `release` into your branch.
+
+```
+# I like the "--edit --log --verbose" parameters, but they are
+# not required.
+git merge upstream/release
+```
+
+3. `BuildInfo.cpp` will have a conflict with the version number.
+   Resolve it with the version from `develop` - the higher version.
+4. Push your branch to your repo (or `upstream` if you have permission),
+   and open a normal PR against `develop`. The "High level overview" can
+   simply indicate that this is a merge of the RC. The "Context" should
+   summarize the changes from the RC. Include the following text
+   prominently:
+
+```
+This PR must be merged manually using a push. Do not use the Github UI.
+```
+
+5. Depending on the complexity of the changes, and/or merge conflicts,
+   the PR may need a thorough review, or just a sign-off that the
+   merge was done correctly.
+6. If `develop` is updated before this PR is merged, do not merge
+   `develop` back into your branch. Instead rebase preserving merges,
+   or do the merge again. (See also the `rerere` git config setting.)
+
+```
+git rebase --rebase-merges upstream/develop
+# OR
+git reset --hard upstream/develop
+git merge upstream/release
+```
+
+7. When the PR is ready, push it to `develop`.
+
+```
+git fetch upstreams
+
+# Make sure the commits look right
+git log --show-signature "upstream/develop^..HEAD"
+
+git push upstream-push mergeABCrcD:develop
+
+git fetch upstreams
+```
+
+Development on `develop` can proceed as normal.
+
+#### Final releases
+
+A final release is any release that is not a beta or RC, such as 2.2.0.
+
+Only code that has already been tested and vetted across all three
+platforms should be included in a final release. Most of the time, that
+means that the commit immediately preceding the commit setting the
+version number will be an RC. Occasionally, there may be last-minute bug
+fixes included as well. If so, those bug fixes must have been tested
+internally as if they were RCs (at minimum, ensuring unit tests pass,
+and the app starts, syncs, and stops cleanly across all three
+platforms.)
+
+_If in doubt, make an RC first._
+
+The process for building a final release is very similar to [the process
+for building a beta](#making-the-release), except the code will be
+moving from `release` to `master` instead of from `develop` to
+`release`, and both branches will be pushed at the same time.
+
+1. Ensure there is no old `master-next` branch hanging around.
+   Then make a `master-next` branch that only changes the version
+   number. As above, or using the
+   [update-version] script.
+2. Create a Pull Request for `master-next` with **`master`** as
+   the base branch. Instead of the default template, reuse and update
+   the message from the previous final release. Include the following verbiage
+   somewhere in the description:
+
+```
+The base branch is `master`. This PR branch will be pushed directly to
+`release` and `master` (not squashed or rebased, and not using the
+GitHub UI).
+```
+
+7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
+   offline, but at least one approval will be needed on the PR.
+   - If issues are discovered during testing, close the PR, delete
+     `master-next`, and move development back to `release`, [issuing
+     more RCs as necessary](#release-candidates-after-the-first)
+8. Once everything is ready to go, push to `release` and `master`.
+
+```
+git fetch upstreams
+
+# Just to be safe, do dry runs first:
+git push --dry-run upstream-push master-next:release
+git push --dry-run upstream-push master-next:master
+
+# If everything looks right, push the branch
+git push upstream-push master-next:release
+git push upstream-push master-next:master
+
+# Check that all of the branches are updated
+git fetch upstreams
+git log -1 --oneline
+# The output should look like:
+# 0123456789 (HEAD -> upstream/master-next, upstream/master,
+#            upstream/release) Set version to A.B.0
+# Note that both upstream/release and upstream/master must be on this
+# commit.
+# Other branches, including some from upstream-push, may also be
+# present.
+```
+
+9. Tag the release, too.
+
+```
+git tag <version number>
+git push upstream-push <version number>
+```
+
+10. Delete the `master-next` branch on the repo. Use the Github UI or:
+
+```
+git push --delete upstream-push master-next
+```
+
+11. [Create a new release on
+    Github](https://github.com/XRPLF/rippled/releases). Be sure that
+    "Set as the latest release" is checked.
+12. Open a PR to update the [API-CHANGELOG](API-CHANGELOG.md) and `API-VERSION-[n].md` with the changes for this release (if any are missing).
+13. Finally, [reverse merge the release into `develop`](#follow-up-reverse-merge).
+
+#### Special cases: point releases, hotfixes, etc.
+
+On occasion, a bug or issue is discovered in a version that already
+had a final release. Most of the time, development will have started
+on the next version, and will usually have changes in `develop`
+and often in `release`.
+
+Because git history is kept as linear as possible, any fix and new
+version will need to be applied against `master`.
+
+The process for building a hotfix release is very similar to [the
+process for building release candidates after the
+first](#release-candidates-after-the-first) and [for building a final
+release](#final-releases), except the changes will be done against
+`master` instead of `release`.
+
+If there is only a single issue for the hotfix, the work can be done in
+any branch. When it's ready to merge, jump to step 3 using your branch
+instead of `master-next`.
+
+1. Create a `master-next` branch from `master`.
+
+```
+git checkout --no-track -b master-next upstream/master
+git push upstream-push
+git fetch upstreams
+```
+
+2. Open any PRs for the pending hotfix using `master-next` as the base,
+   so they can be merged directly in to it. Unlike `develop`, though,
+   `master-next` can be thrown away and recreated if necessary.
+3. Once the hotfix is ready, create a version commit using the same
+   steps as above, or use the
+   [update-version] script.
+4. Create a Pull Request for `master-next` with **`master`** as
+   the base branch. Instead of the default template, reuse and update
+   the message from the previous final release. Include the following verbiage
+   somewhere in the description:
+
+```
+The base branch is `master`. This PR branch will be pushed directly to
+`master` (not squashed or rebased, and not using the GitHub UI).
+```
+
+7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
+   offline, but at least one approval will be needed on the PR.
+   - If issues are discovered during testing, update `master-next` as
+     needed, but ensure that the changes are properly squashed, and the
+     version setting commit remains last
+8. Once everything is ready to go, push to `master` **only**.
+
+```
+git fetch upstreams
+
+# Just to be safe, do a dry run first:
+git push --dry-run upstream-push master-next:master
+
+# If everything looks right, push the branch
+git push upstream-push master-next:master
+
+# Check that all of the branches are updated
+git fetch upstreams
+git log -1 --oneline
+# The output should look like:
+# 0123456789 (HEAD -> upstream/master-next, upstream/master) Set version
+#            to 2.4.1
+# Note that upstream/master must be on this commit. upstream/release and
+# upstream/develop should not.
+# Other branches, including some from upstream-push, may also be
+# present.
+```
+
+9. Tag the release, too.
+
+```
+git tag <version number>
+git push upstream-push <version number>
+```
+
+9. Delete the `master-next` branch on the repo.
+
+```
+git push --delete upstream-push master-next
+```
+
+10. [Create a new release on
+    Github](https://github.com/XRPLF/rippled/releases). Be sure that
+    "Set as the latest release" is checked.
+
+Once the hotfix is released, it needs to be reverse merged into
+`develop` as soon as possible. It may also need to be merged into
+`release` if a release candidate is under development.
+
+1. Create a branch in your own repo, based on `upstream/develop`.
+   The branch name is not important, but could include "mergeNNN".
+   E.g. For release 2.2.3, use `merge223`.
+
+```
+git fetch upstreams
+
+git checkout --no-track -b merge223 upstream/develop
+```
+
+2. Merge master into your branch.
+
+```
+# I like the "--edit --log --verbose" parameters, but they are
+# not required.
+git merge upstream/master
+```
+
+3. `BuildInfo.cpp` will have a conflict with the version number.
+   Resolve it with the version from `develop` - the higher version.
+4. Push your branch to your repo, and open a normal PR against
+   `develop`. The "High level overview" can simply indicate that this
+   is a merge of the hotfix version. The "Context" should summarize
+   the changes from the hotfix. Include the following text
+   prominently:
+
+```
+This PR must be merged manually using a --ff-only merge. Do not use the Github UI.
+```
+
+5. Depending on the complexity of the hotfix, and/or merge conflicts,
+   the PR may need a thorough review, or just a sign-off that the
+   merge was done correctly.
+6. If `develop` is updated before this PR is merged, do not merge
+   `develop` back into your branch. Instead rebase preserving merges,
+   or do the merge again. (See also the `rerere` git config setting.)
+
+```
+git rebase --rebase-merges upstream/develop
+# OR
+git reset --hard upstream/develop
+git merge upstream/master
+```
+
+7. When the PR is ready, push it to `develop`.
+
+```
+git fetch upstreams
+
+# Make sure the commits look right
+git log --show-signature "upstream/develop..HEAD"
+
+git push upstream-push HEAD:develop
+```
+
+Development on `develop` can proceed as normal. It is recommended to
+create a beta (or RC) immediately to ensure that everything worked as
+expected.
+
+##### An even rarer scenario: A hotfix on an old release
+
+Historically, once a final release is tagged and packages are released,
+versions older than the latest final release are no longer supported.
+However, there is a possibility that a very high severity bug may occur
+in a non-amendment blocked version that is still being run by
+a significant fraction of users, which would necessitate a hotfix / point
+release to that version as well as any later versions.
+
+This scenario would follow the same basic procedure as above,
+except that _none_ of `develop`, `release`, or `master`
+would be touched during the release process.
+
+In this example, consider if version 2.1.1 needed to be patched.
+
+1. Create two branches in the main (`upstream`) repo.
+
+```
+git fetch upstreams
+
+# Create a base branch off the tag
+git checkout --no-track -b master-2.1.2 2.1.1
+git push upstream-push
+
+# Create a working branch
+git checkout --no-track -b master212-next master-2.1.2
+git push upstream-push
+
+git fetch upstreams
+```
+
+2. Work continues as above, except using `master-2.1.2`as
+   the base branch for any merging, packaging, etc.
+3. After the release is tagged and packages are built, you could
+   potentially delete both branches, e.g. `master-2.1.2` and
+   `master212-next`. However, it may be useful to keep `master-2.1.2`
+   around indefinitely for reference.
+4. Assuming that a hotfix is also released for the latest
+   version in parallel with this one, or if the issue is
+   already fixed in the latest version, do no do any
+   reverse merges. However, if it is not, it probably makes
+   sense to reverse merge `master-2.1.2` into `master`,
+   release a hotfix for _that_ version, then reverse merge
+   from `master` to `develop`. (Please don't do this unless absolutely
+   necessary.)
 
 [contrib]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
 [squash]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits
@@ -641,3 +1184,5 @@ are described in [RELEASING.md](./RELEASING.md).
 [xrpld]: https://github.com/XRPLF/rippled
 [signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification
 [setup-upstreams]: ./bin/git/setup-upstreams.sh
+[squash-branches]: ./bin/git/squash-branches.sh
+[update-version]: ./bin/git/update-version.sh

README.md

@@ -54,7 +54,6 @@ Here are some good places to start learning the source code:
 | `./docs`   | Source documentation files and doxygen config. |
 | `./cfg`    | Example configuration files.                   |
 | `./src`    | Source code.                                   |
-| `./crates` | Rust source code.                              |
 
 Some of the directories under `src` are external repositories included using
 git-subtree. See those directories' README files for more details.

RELEASING.md

@@ -1,152 +0,0 @@
-# Branching and Release Management
-
-This document describes how we branch, release, and merge releases back into `develop`.
-It does not define version naming
-(e.g., what constitutes a major-minor, patch, or beta release).
-
-Examples use `X.Y` for a release line:
-`X` and `Y` are placeholders, while the trailing `x` is literal,
-e.g., `release/X.Y.x` is `release/3.4.x` for the `3.4` line.
-
-## Branches
-
-| Branch          | Purpose                                                                                   |
-| :-------------- | :---------------------------------------------------------------------------------------- |
-| `develop`       | Main development branch. Betas and the first RC of a major-minor release are tagged here. |
-| `staging/X.Y.x` | Where fixes for the `X.Y` line are developed and RCs are prepared.                        |
-| `release/X.Y.x` | The last public RC or release of the `X.Y` line.                                          |
-
-A release line is named `X.Y.x`
-because one branch serves every patch release of that line (`X.Y.0`, `X.Y.1`, `X.Y.2`, ...).
-The `/` groups branches hierarchically,
-so tools can filter them and protection rules can target `release/*` and `staging/*`.
-
-## Principles
-
-- **Releases are merged back into `develop`, never cherry-picked or rebased onto it.**
-  Cherry-picked and rebased commits get new hashes,
-  so Git can't tell that `develop` already has them.
-  Future merges then replay them and produce artificial conflicts,
-  and it's hard to verify that every fix actually reached `develop`.
-  Merging keeps a single history:
-  Git knows exactly which release commits `develop` contains,
-  and no fix is left behind.
-- **Branches only move forward.**
-  `develop`, `staging/X.Y.x`, and `release/X.Y.x` are never rewritten.
-- **Cherry-picking only goes from `develop` to a staging branch**,
-  for fixes that must get into a release after the code freeze
-  (see [Emergency Fixes From `develop`](#emergency-fixes-from-develop)).
-- **Security fixes are prepared privately and published with the release that contains them**,
-  so vulnerabilities are not disclosed prematurely.
-
-## Release Lifecycle
-
-This diagram shows a major-minor release and its first patch release.
-The staging and release branches are drawn as one line.
-
-```text
-develop                            staging/X.Y.x & release/X.Y.x
-   │
-   ├── Tag: X.Y.0-b1
-   ├── Tag: X.Y.0-bN
-   ├── Tag: X.Y.0-rc1 ───────────────┐ (branches created)
-   │                                 │
-   │  (development continues)        ├── Fixes
-   │                                 ├── Tag: X.Y.0-rcN
-   │                                 ├── Tag: X.Y.0 (final)
-   ◀──── (merge) ────────────────────┤
-   │                                 ├── Fixes
-   │                                 ├── Tag: X.Y.1-rcN
-   │                                 ├── Tag: X.Y.1 (final)
-   ◀──── (merge) ────────────────────┤
-   │
-   ▼
-```
-
-### Betas, First RC & Branching
-
-> [!NOTE]
-> This phase applies only to a new major-minor release (e.g., `X.Y.0`).
-> Patch releases work on the existing branches of the line.
-
-1. **Betas:** All beta versions (e.g., `X.Y.0-b1`) are built and tagged directly on `develop`.
-2. **First RC:** We release the first RC (`X.Y.0-rc1`)
-   once everything that should be included in the release has been merged.
-3. **Branches:** `staging/X.Y.x` and `release/X.Y.x` are created from `develop`
-   at the commit tagged `X.Y.0-rc1`.
-   The first RC also kicks off the QE process.
-4. **Code freeze:** No new features or unrelated changes are pulled from `develop`
-   into `staging/X.Y.x` or `release/X.Y.x`.
-   Only critical stabilization fixes go into the line.
-5. **No large changes on `develop`:** Until `X.Y.0` is [merged back](#merging-back-into-develop),
-   large changes (e.g., big refactors, moving or renaming many files, mass reformatting)
-   are not merged into `develop`,
-   so that fixes on the line and the merge back don't run into conflicts.
-
-### Release Candidates
-
-1. Fixes are developed against `staging/X.Y.x`.
-2. When ready, a new RC is created on `staging/X.Y.x`,
-   and `release/X.Y.x` is fast-forwarded to it.
-
-RCs that contain unpublished security fixes are not published,
-and don't touch the public branches.
-
-RCs are not merged back into `develop`:
-`X.Y.0-rc1` is tagged on `develop` itself,
-and all later changes reach `develop` with the [final release](#final-release).
-
-### Final Release
-
-Security fixes become public as soon as they reach the public repo,
-so these steps happen only once the release is ready to be published,
-one right after the other.
-
-1. Unpublished security fixes, if any, are merged into `staging/X.Y.x`.
-2. `release/X.Y.x` is fast-forwarded to `staging/X.Y.x`,
-   and the release is tagged on it.
-3. The release is immediately [merged back into `develop`](#merging-back-into-develop).
-   For a major-minor release, this lifts the freeze on large changes in `develop`.
-
-### Merging Back Into `develop`
-
-The merge back is a regular PR into `develop`
-whose branch contains a real merge commit of the release tag:
-
-1. Create a branch from `develop`, run `git merge --no-ff <tag>`, and resolve any conflicts.
-2. Once the PR is approved, `develop` is fast-forwarded to the PR branch,
-   so the merge commit lands as it is.
-   Never squash or rebase it.
-   Never add it to the merge queue either: the queue squashes PRs, which would drop the merge commit.
-3. If `develop` moves while the PR is open, redo the merge on top of the new `develop`.
-
-After the merge, `git log develop..<tag>` must be empty.
-
-## Special Cases
-
-### Emergency Fixes From `develop`
-
-If a commit was merged to `develop`
-and needs to be included in a release after the code freeze:
-
-1. Create a PR that cherry-picks the commit onto `staging/X.Y.x`.
-2. Leave `develop` as it is, with no reverts.
-3. Follow the [release candidates](#release-candidates) process as usual.
-
-When the release is later merged back into `develop`,
-both sides already contain the same change,
-so the merge usually resolves it cleanly or with a trivial conflict.
-From Git's perspective, the cherry-picked commit then becomes part of `develop` too.
-
-### Several Supported Lines
-
-When a fix must ship in more than one supported line (e.g., `X.Y` and `X.(Y+1)`),
-the lines are merged upwards rather than cherry-picked between:
-
-1. The fix goes into the oldest line first.
-2. After that line's release,
-   its `release/X.Y.x` is merged into the staging branch of the next newer line,
-   and so on up to the newest line.
-3. The newest line is merged back into `develop` as usual.
-
-This way every newer line, and eventually `develop`, contains the history of the older lines.

bin/check-nix-store-refs.sh

@@ -1,111 +0,0 @@
-#!/usr/bin/env bash
-# Fail if a binary under <path> records a /nix/store path it resolves at run
-# time. See docs/build/nix.md#prebuilt-packages for why that matters.
-#
-# <path> is a file or a directory. macOS: nothing may reference the store, so
-# point it at whole trees. Linux: the toolchain always writes the store into
-# PT_INTERP and RUNPATH, so only at what cmake/PatchNixBinary.cmake retargets.
-#
-# Only Mach-O / ELF is inspected. Static archives hold store paths in debug info
-# alone; the scripts in a Conan cache are all git hook samples and autotools
-# scratch, 36 false positives to 0 real.
-#
-# Usage: bin/check-nix-store-refs.sh <path>
-
-set -euo pipefail
-
-if [ "$#" -ne 1 ]; then
-    echo "usage: $0 <path>" >&2
-    exit 2
-fi
-
-if [ ! -e "$1" ]; then
-    echo "$0: no such path: $1" >&2
-    exit 2
-fi
-
-case "$(uname -s)" in
-    Darwin)
-        format=Mach-O
-        recorded_paths=macho_recorded_paths
-        tool=otool
-        ;;
-    Linux)
-        format=ELF
-        recorded_paths=elf_recorded_paths
-        tool=readelf
-        ;;
-    *)
-        echo "Unsupported OS - skipping the Nix store reference check."
-        exit 0
-        ;;
-esac
-
-# `pipefail` would catch this too, but only as a bare nonzero exit.
-if ! command -v "${tool}" >/dev/null; then
-    echo "$0: ${tool} not found; cannot inspect binaries" >&2
-    exit 2
-fi
-
-# Both list what the file records. `ldd` would answer what this machine resolves
-# now, which is wrong both ways: store paths for a correctly patched binary,
-# silence for a store RUNPATH that resolves nowhere.
-
-# `name` covers LC_ID_DYLIB and LC_LOAD*_DYLIB, `path` covers LC_RPATH.
-macho_recorded_paths() {
-    otool -l "$1" | sed -nE 's#^ *(name|path) ([^ ]*).*#\2#p'
-}
-
-# RPATH and RUNPATH are colon-separated.
-elf_recorded_paths() {
-    readelf -ldW "$1" |
-        sed -nE \
-            -e 's#.*program interpreter: ([^]]*)\].*#\1#p' \
-            -e 's#.*\((RPATH|RUNPATH|NEEDED)\).*\[([^]]*)\].*#\2#p' |
-        tr ':' '\n'
-}
-
-checked=0
-skipped=0
-leaked=0
-
-while IFS= read -r file; do
-    case "$(file -b "${file}" 2>/dev/null)" in
-        *"${format}"*) ;;
-        *)
-            skipped=$((skipped + 1))
-            continue
-            ;;
-    esac
-    checked=$((checked + 1))
-
-    # Filter after extracting, or a search path starting elsewhere ($ORIGIN)
-    # hides the rest. `sed` not `grep`: grep calls "no matches" a failure, and
-    # the `|| true` that would need masks a broken pipeline too.
-    refs="$("${recorded_paths}" "${file}" | sed -n '\#^/nix/store/#p' | sort -u)"
-    if [ -n "${refs}" ]; then
-        leaked=$((leaked + 1))
-        echo "::error file=${file}::references the Nix store at run time"
-        echo "${file}"
-        echo "${refs}" | sed 's/^/    /'
-    fi
-done < <(find "$1" -type f \( -perm -u+x -o -name '*.dylib' -o -name '*.so*' \))
-
-echo "$1: checked ${checked}, skipped ${skipped}, ${leaked} with Nix store references."
-
-if [ "${leaked}" -ne 0 ]; then
-    cat >&2 <<'EOF'
-
-Fixes, in order of preference:
-  - A Conan package built before this check existed: drop it
-    (`conan remove '<name>/*'`) and rebuild.
-  - A binary that should have been retargeted to the system loader: check that
-    cmake/PatchNixBinary.cmake ran for it.
-  - Link the macOS system library instead of the Nix one - see
-    libresolvSystemStub in nix/darwin.nix.
-  - No system library exists (libstdc++): link it statically.
-  - None of the above: pin the toolchain into the package ID, following
-    `user.package:libc_version` in conan/profiles/ci.
-EOF
-    exit 1
-fi

bin/check-tools.sh

@@ -15,46 +15,25 @@
 #   - Windows: the core build tools only (CMake, Conan, Git, Python).
 #              MSVC is expected to be provided separately and is not checked here.
 #
-# Some tools (clang-format, clang-tidy, doxygen, gcovr, gh, git-cliff, gpg,
-# pre-commit, run-clang-tidy) are present in our Linux CI images and in local
-# development setups, but not in the macOS CI environment. They are checked
-# everywhere except when running in CI on macOS.
-#
-# Tools that Nix also exposes under a version-suffixed name (`clang-tidy-22`,
-# `g++-15`, ...) are probed under both names: a suffixed name can break while
-# the plain one still works (see mkVersionedToolLinks in nix/packages.nix).
-#
-# Tools scoped to a single dev shell rather than to commonPackages are checked
-# only in that shell, keyed off XRPL_DEVSHELL.
+# Some tools (clang-format, doxygen, gcovr, gh, git-cliff, gpg, pre-commit,
+# run-clang-tidy) are present in our Linux CI images and in local development
+# setups, but not in the macOS CI environment. They are checked everywhere
+# except when running in CI on macOS.
 #
 # Environment variables:
 #   CI                      if set, skip the tools above when on macOS.
 #   CHECK_TOOLS_SKIP_CLONE  if set, skip the git-over-HTTPS connectivity check.
-#   XRPL_DEVSHELL           active dev shell; selects shell-specific tools.
 
 set -uo pipefail
 
-# Version suffixes of the Nix tool links, tracking nix/packages.nix.
-gcc_version=15
-llvm_version=22
-
 missing=()
 checked=0
 
-# tool_path <name>
-# Fully resolved path of a tool, so the snapshots record which derivation
-# provides it. Prints nothing when it isn't on PATH.
-tool_path() {
-    local path
-    path="$(command -v "$1" 2>/dev/null)" || return 0
-    readlink -f "${path}" 2>/dev/null || printf '%s' "${path}"
-}
-
 # check <name> [probe-command...]
 # Runs the probe (default: "<name> --version"), capturing both stdout and
-# stderr, and prints three lines: the status and name, the first non-blank line
-# of the probe output (its version, or the error when it failed), and the tool's
-# resolved path. Records <name> as missing if it is not found or exits non-zero.
+# stderr, and prints one aligned line: the status, the name, and the first
+# non-blank line of the probe output (its version). Records <name> as missing
+# if the command is not found or exits non-zero.
 check() {
     local name="$1"
     shift
@@ -64,17 +43,14 @@ check() {
     fi
 
     checked=$((checked + 1))
-    local output version path
-    path="$(tool_path "${name}")"
+    local output version
     if output="$("${probe[@]}" 2>&1)"; then
-        printf '  ✅ %s\n' "${name}"
+        version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
+        printf '  [ ok ] %-20s %s\n' "${name}" "${version}"
     else
-        printf '  ❌ %s\n' "${name}"
+        printf '  [MISS] %s\n' "${name}"
         missing+=("${name}")
     fi
-    version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
-    printf '     %s\n' "${version:-(no output)}"
-    printf '     %s\n' "${path:-(not found)}"
 }
 
 case "$(uname -s)" in
@@ -106,9 +82,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     echo "Development tooling:"
     check ccache
     check clang
-    check "clang-${llvm_version}"
     check clang++
-    check "clang++-${llvm_version}"
     check ClangBuildAnalyzer
     check curl
     check file
@@ -127,14 +101,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     # setups, but not in the macOS CI environment. So check them everywhere
     # except when running in CI on macOS.
     if [ "${os}" = "linux" ] || [ -z "${CI:-}" ]; then
-        check clang-apply-replacements
-        check "clang-apply-replacements-${llvm_version}"
         check clang-format
-        check "clang-format-${llvm_version}"
-        # clang-tidy leads --version with the LLVM banner, not the version.
-        tidy_probe="--version | grep -m1 -oE 'LLVM version [0-9.]+'"
-        check clang-tidy sh -c "clang-tidy ${tidy_probe}"
-        check "clang-tidy-${llvm_version}" sh -c "clang-tidy-${llvm_version} ${tidy_probe}"
         check dot
         check doxygen
         check gcovr
@@ -145,7 +112,6 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
         # pre-commit, or its alternative implementation prek
         check pre-commit sh -c 'pre-commit --version || prek --version'
         check run-clang-tidy run-clang-tidy --help
-        check "run-clang-tidy-${llvm_version}" "run-clang-tidy-${llvm_version}" --help
     fi
 fi
 
@@ -160,32 +126,19 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     check cargo-audit cargo audit --version
     check cargo-llvm-cov cargo llvm-cov --version
     check cargo-nextest cargo nextest --version
-    check clippy-driver
+    check clippy clippy-driver --version
     check rust-analyzer
-    check rust-nightly rust-nightly run rustc --version
     check rustc
     check rustfmt
 fi
 
-# Lean4 is in the formal-verification shell only, not in commonPackages.
-if [ "${XRPL_DEVSHELL:-}" = "formal-verification" ]; then
-    echo
-    echo "Formal verification toolchain:"
-    check lean
-    check lake
-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
     echo
     echo "GCC toolchain:"
     check gcc
-    check "gcc-${gcc_version}"
     check g++
-    check "g++-${gcc_version}"
-    check cpp
-    check "cpp-${gcc_version}"
     check gcov
 
     echo
@@ -210,9 +163,9 @@ else
     checked=$((checked + 1))
     tmp_clone="$(mktemp -d)"
     if git clone --depth 1 https://github.com/XRPLF/actions.git "${tmp_clone}/actions" >/dev/null 2>&1; then
-        printf '  ✅ git clone over HTTPS\n'
+        printf '  [ ok ] git clone over HTTPS\n'
     else
-        printf '  ❌ git clone over HTTPS\n'
+        printf '  [MISS] git clone over HTTPS\n'
         missing+=("git-https-clone")
     fi
     rm -rf "${tmp_clone}"
@@ -220,9 +173,9 @@ fi
 
 echo
 if [ "${#missing[@]}" -eq 0 ]; then
-    echo "✅ All ${checked} checked tools are present and runnable."
+    echo "All ${checked} checked tools are present and runnable."
 else
-    echo "❌ Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
+    echo "Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
     for tool in "${missing[@]}"; do
         echo "  - ${tool}" >&2
     done

bin/git/update-version.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]; then
+    name=$(basename $0)
+    cat <<-USAGE
+    Usage: $name workbranch base/branch version
+
+    * workbranch will be created locally from base/branch. If it exists,
+        it will be reused, so make sure you don't overwrite any work.
+    * base/branch may be specified as user:branch to allow easy copying
+        from Github PRs.
+USAGE
+    exit 0
+fi
+
+work="$1"
+shift
+
+base=$(echo "$1" | sed "s/:/\//")
+shift
+
+version=$1
+shift
+
+set -e
+
+git fetch upstreams
+
+git checkout -B "${work}" --no-track "${base}"
+
+push=$(git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
+    2>/dev/null) || true
+if [[ "${push}" != "" ]]; then
+    echo "Warning: ${push} may already exist."
+fi
+
+build=$(find -name BuildInfo.cpp)
+sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} >version.cpp &&
+    diff "${build}" version.cpp && exit 1 ||
+    mv -vi version.cpp ${build}
+
+git diff
+
+git add ${build}
+
+git commit -S -m "Set version to ${version}"
+
+git log --oneline --first-parent ${base}^..
+
+cat <<PUSH
+
+-------------------------------------------------------------------
+This script will not push. Verify everything is correct, then push
+to your repo, and create a PR as described in CONTRIBUTING.md.
+-------------------------------------------------------------------
+PUSH

bin/pre-commit/check_rust_coverage_attrs.py

@@ -1,149 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check that Rust unit tests stay out of the coverage report.
-
-cargo-llvm-cov instruments the test code along with everything else, so a test
-module that is not excluded counts its own body as covered and inflates the
-reported number. Excluding it takes two attributes:
-
-  * every `#[cfg(test)]` module carries
-    `#[cfg_attr(coverage_nightly, coverage(off))]`;
-  * every crate root (lib.rs, main.rs) carries
-    `#![cfg_attr(coverage_nightly, feature(coverage_attribute))]`, which the
-    attribute above needs in order to compile.
-
-Both are inert outside the coverage job: cargo-llvm-cov defines
-`coverage_nightly` only when it runs on a nightly toolchain.
-
-The crate-root gate is checked even in a crate that has no tests yet, because
-that is what lets the first test module added later carry the attribute without
-a build failure. Missing it is a hard error, so it cannot go unnoticed; a
-missing `coverage(off)` fails open, which is why this check exists.
-
-Matching is on exact attribute text, which works because `cargo fmt` runs over
-the whole workspace in the hook ahead of this one: rustfmt puts every attribute
-on its own line and normalizes what is inside it, turning `#[cfg( test )]`
-and `#[cfg(test,)]` alike into `#[cfg(test)]`. So there is nothing here that
-parses Rust. The price is that a cfg this file does not spell out literally --
-`all(test, ...)`, `any(test, ...)`, `not(test)` -- is reported rather than
-classified, on the grounds that guessing at coverage semantics is how a check
-like this ends up quietly wrong.
-
-Usage: ./bin/pre-commit/check_rust_coverage_attrs.py <file1> <file2> ...
-
-Exit status is non-zero if any violation is found.
-"""
-
-import re
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-CRATE_ROOTS = {"lib.rs", "main.rs"}
-
-FEATURE_ATTR = "#![cfg_attr(coverage_nightly, feature(coverage_attribute))]"
-COVERAGE_OFF_ATTR = "#[cfg_attr(coverage_nightly, coverage(off))]"
-CFG_TEST_ATTR = "#[cfg(test)]"
-
-# Any other cfg that mentions `test`. String literals are blanked before this
-# runs, so `feature = "test"` does not read as the `test` cfg.
-RE_CFG_MENTIONS_TEST = re.compile(r"^#\[cfg\(.*\btest\b.*\)\]$")
-RE_STRING = re.compile(r'"(?:[^"\\]|\\.)*"')
-RE_MOD = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?mod\s+([A-Za-z_]\w*)")
-
-
-@dataclass(frozen=True)
-class Finding:
-    line: int
-    label: str
-    message: str
-
-
-def _check_module(attrs: list[str], line: int, name: str) -> list[Finding]:
-    """Findings for one module, given the attributes attached to it."""
-    if COVERAGE_OFF_ATTR in attrs:
-        return []  # excluded from coverage; which cfg gates it does not matter
-    if CFG_TEST_ATTR in attrs:
-        return [
-            Finding(
-                line,
-                "missing-coverage-off",
-                f"`mod {name}` is #[cfg(test)] but not excluded from coverage; "
-                f"add {COVERAGE_OFF_ATTR}",
-            )
-        ]
-    unclassified = [
-        attr for attr in attrs if RE_CFG_MENTIONS_TEST.match(RE_STRING.sub('""', attr))
-    ]
-    if unclassified:
-        return [
-            Finding(
-                line,
-                "unclassified-cfg",
-                f"`mod {name}` is gated on {unclassified[0]}, which this check "
-                f"cannot tell apart from a module that ships in the library; "
-                f"add {COVERAGE_OFF_ATTR} if it is test-only, or teach this "
-                f"check the cfg if it is not",
-            )
-        ]
-    return []
-
-
-def _check_test_modules(lines: list[str]) -> list[Finding]:
-    """Findings for every test module that is not excluded from coverage."""
-    findings: list[Finding] = []
-    attrs: list[str] = []
-    attrs_line = 0
-    for number, raw in enumerate(lines, start=1):
-        stripped = raw.strip()
-        # Blank lines and comments are allowed between an attribute and its item.
-        if not stripped or stripped.startswith("//"):
-            continue
-        if stripped.startswith("#["):
-            if not attrs:
-                attrs_line = number
-            attrs.append(stripped)
-            continue
-        module = RE_MOD.match(stripped)
-        if module is not None and attrs:
-            findings += _check_module(attrs, attrs_line, module.group(1))
-        attrs = []
-    return findings
-
-
-def _check_crate_root(name: str, lines: list[str]) -> list[Finding]:
-    """A finding if a crate root is missing the coverage_attribute feature gate."""
-    if name not in CRATE_ROOTS:
-        return []
-    if any(line.strip() == FEATURE_ATTR for line in lines):
-        return []
-    return [
-        Finding(
-            1,
-            "missing-feature-gate",
-            f"crate root is missing {FEATURE_ATTR}",
-        )
-    ]
-
-
-def check_source(name: str, text: str) -> list[Finding]:
-    """Findings for one file's contents; `name` is its base name (lib.rs, ...)."""
-    lines = text.splitlines()
-    return _check_crate_root(name, lines) + _check_test_modules(lines)
-
-
-def check_file(path: Path) -> list[Finding]:
-    return check_source(path.name, path.read_text(encoding="utf-8"))
-
-
-def main() -> int:
-    total = 0
-    for path in (Path(name) for name in sys.argv[1:]):
-        for finding in check_file(path):
-            total += 1
-            print(f"{path}:{finding.line}: {finding.label}: {finding.message}")
-    return 1 if total else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bin/pre-commit/fix_gtest_names.py

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Rewrites gtest names to the required style in this project: the suite name is
-CamelCase, the test-case name is snake_case.
-
-    TEST(SuiteName, test_case_name)
-
-The gtest `DISABLED_` prefix is kept verbatim on either name.
-
-Both conversions fold acronyms the way a reader expects:
-`SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`, not
-`set_and_reset_account_txn_i_d`.
-
-The first argument of `TEST_F`, `TEST_P`, `TYPED_TEST` and `TYPED_TEST_P` is a
-fixture class rather than a free identifier, so rewriting it here would leave
-the class it names behind. Those are reported for a human to rename (clang-tidy
-checks the class declaration itself, via readability-identifier-naming).
-
-Usage: ./bin/pre-commit/fix_gtest_names.py <file1> <file2> ...
-"""
-
-import re
-import sys
-from collections import Counter
-from pathlib import Path
-
-# A test-case definition, `MACRO(SuiteOrFixture, TestName)`, anchored at the
-# start of a line so that commented-out definitions and project macros that
-# merely look similar (`TEST_EXPECT(...)`) are left alone. The `\s*` between
-# arguments allows for a definition clang-format wrapped over several lines.
-PATTERN = re.compile(
-    r"(?P<head>^[ \t]*(?P<macro>TYPED_TEST_P|TYPED_TEST|TEST_F|TEST_P|TEST)\s*\(\s*)"
-    r"(?P<suite>\w+)(?P<mid>\s*,\s*)(?P<name>\w+)(?P<tail>\s*\))",
-    re.MULTILINE,
-)
-
-# The macros whose first argument names a fixture class, not a free identifier.
-FIXTURE_MACROS = ("TEST_F", "TEST_P", "TYPED_TEST", "TYPED_TEST_P")
-
-DISABLED = "DISABLED_"
-
-ACRONYM_BOUNDARY = re.compile(r"([A-Z]+)([A-Z][a-z])")
-WORD_BOUNDARY = re.compile(r"([a-z\d])([A-Z])")
-
-
-def _split_disabled(name: str) -> tuple[str, str]:
-    """Splits off gtest's `DISABLED_` prefix, which is kept verbatim."""
-    if name.startswith(DISABLED):
-        return DISABLED, name[len(DISABLED) :]
-    return "", name
-
-
-def snake_case(name: str) -> str:
-    """Returns the name in snake_case, leaving acronyms whole.
-
-    `SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`,
-    `parseStatRSSkB` -> `parse_stat_rs_sk_b`.
-    """
-    prefix, core = _split_disabled(name)
-    core = ACRONYM_BOUNDARY.sub(r"\1_\2", core)
-    return prefix + WORD_BOUNDARY.sub(r"\1_\2", core).lower()
-
-
-def camel_case(name: str) -> str:
-    """Returns the name in CamelCase, capitalizing each underscored word.
-
-    Only the letters that have to change are touched, so acronyms survive: a
-    conversion that went via snake_case would turn `SHAMapTest` into
-    `ShaMapTest`, whereas here it is already CamelCase and stays put.
-    `json_value` -> `JsonValue`, `parseStatRSSkB` -> `ParseStatRSSkB`.
-    """
-    prefix, core = _split_disabled(name)
-    return prefix + "".join(w[:1].upper() + w[1:] for w in core.split("_") if w)
-
-
-def _corrected(match: re.Match) -> tuple[str, str]:
-    """Returns the suite and test-case names this definition should end up with."""
-    suite = match["suite"]
-    return (
-        suite if match["macro"] in FIXTURE_MACROS else camel_case(suite),
-        snake_case(match["name"]),
-    )
-
-
-def fix_source(text: str) -> tuple[str, list[str]]:
-    """Returns the corrected text and one `line: message` report per bad name."""
-    # gtest joins the suite and test names into one class name, so two test
-    # cases whose joined names agree cannot coexist: `TEST(a, b_c)` and
-    # `TEST(a_b, c)` both define `a_b_c_Test`. A rename that would introduce
-    # such a clash is reported for a human instead of applied.
-    joined = Counter("_".join(_corrected(m)) for m in PATTERN.finditer(text))
-    reports = []
-
-    def rewrite(match: re.Match) -> str:
-        suite, name = match["suite"], match["name"]
-        new_suite, new_name = _corrected(match)
-        line = text.count("\n", 0, match.start()) + 1
-
-        if match["macro"] in FIXTURE_MACROS and camel_case(suite) != suite:
-            reports.append(
-                f"{line}: fixture '{suite}' is not CamelCase: rename the class "
-                f"to '{camel_case(suite)}' by hand"
-            )
-        if (new_suite, new_name) == (suite, name):
-            return match[0]
-        if joined[f"{new_suite}_{new_name}"] > 1:
-            reports.append(
-                f"{line}: cannot rename '{suite}, {name}' to '{new_suite}, "
-                f"{new_name}': another test case already generates that name"
-            )
-            return match[0]
-        if new_suite != suite:
-            reports.append(f"{line}: renamed suite '{suite}' to '{new_suite}'")
-        if new_name != name:
-            reports.append(f"{line}: renamed test case '{name}' to '{new_name}'")
-        return match["head"] + new_suite + match["mid"] + new_name + match["tail"]
-
-    return PATTERN.sub(rewrite, text), reports
-
-
-def fix_names(path: Path) -> bool:
-    """Corrects one file's gtest names, reporting each on stdout."""
-    original = path.read_text(encoding="utf-8")
-    fixed, reports = fix_source(original)
-    for report in reports:
-        print(f"{path}:{report}")
-    if fixed != original:
-        path.write_text(fixed, encoding="utf-8")
-    return not reports
-
-
-def main() -> int:
-    files = [Path(f) for f in sys.argv[1:]]
-    success = True
-
-    for path in files:
-        success &= fix_names(path)
-
-    return 0 if success else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

bin/pre-commit/test_fix_gtest_names.py

@@ -1,259 +0,0 @@
-#!/usr/bin/env python3
-"""
-Tests for fix_gtest_names.py.
-
-Run directly (no test framework needed):
-    ./bin/pre-commit/test_fix_gtest_names.py
-or under pytest:
-    pytest bin/pre-commit/test_fix_gtest_names.py
-"""
-
-import sys
-import textwrap
-
-from fix_gtest_names import camel_case, fix_source, snake_case
-
-
-def dedent(text: str) -> str:
-    """Removes a fixture's common indentation and its leading newline.
-
-    Lets fixtures be written as indented triple-quoted here-docs while keeping
-    honest 1-based line numbers.
-    """
-    return textwrap.dedent(text).lstrip("\n")
-
-
-def fixed(text: str) -> str:
-    return fix_source(dedent(text))[0]
-
-
-def reports(text: str) -> list[str]:
-    return fix_source(dedent(text))[1]
-
-
-# --- conversion --------------------------------------------------------------
-
-
-def test_snake_case_conversion() -> None:
-    assert snake_case("BadInputs") == "bad_inputs"
-    assert snake_case("mulDiv") == "mul_div"
-    assert snake_case("already_snake") == "already_snake"
-    assert snake_case("base64") == "base64"
-
-
-def test_snake_case_keeps_acronyms_whole() -> None:
-    assert snake_case("SetAndResetAccountTxnID") == "set_and_reset_account_txn_id"
-    assert snake_case("XRPToIOU") == "xrp_to_iou"
-    assert snake_case("STAmountMath") == "st_amount_math"
-
-
-def test_camel_case_conversion() -> None:
-    assert camel_case("json_value") == "JsonValue"
-    assert camel_case("mulDiv") == "MulDiv"
-    assert camel_case("scope") == "Scope"
-    assert camel_case("base64") == "Base64"
-
-
-def test_camel_case_leaves_acronyms_alone() -> None:
-    # A snake_case round-trip would give `ShaMapTest` / `ParseStatmRsSkB` here.
-    assert camel_case("SHAMapTest") == "SHAMapTest"
-    assert camel_case("parseStatmRSSkB") == "ParseStatmRSSkB"
-    assert camel_case("XRPAmount") == "XRPAmount"
-    assert camel_case("CSPRNG") == "CSPRNG"
-
-
-def test_disabled_prefix_preserved() -> None:
-    assert snake_case("DISABLED_FooBar") == "DISABLED_foo_bar"
-    assert snake_case("DISABLED_foo_bar") == "DISABLED_foo_bar"
-    assert snake_case("DISABLED_") == "DISABLED_"
-    assert camel_case("DISABLED_foo_bar") == "DISABLED_FooBar"
-    assert camel_case("DISABLED_") == "DISABLED_"
-
-
-# --- what counts as a test definition ---------------------------------------
-
-
-def test_all_macros_recognized() -> None:
-    code = """
-    TEST(Suite, oneName)
-    TEST_F(Fixture, twoName)
-    TEST_P(Fixture, threeName)
-    TYPED_TEST(Fixture, fourName)
-    TYPED_TEST_P(Fixture, fiveName)
-    """
-    assert fixed(code) == dedent("""
-        TEST(Suite, one_name)
-        TEST_F(Fixture, two_name)
-        TEST_P(Fixture, three_name)
-        TYPED_TEST(Fixture, four_name)
-        TYPED_TEST_P(Fixture, five_name)
-        """)
-
-
-def test_conforming_definitions_untouched() -> None:
-    code = """
-    TEST(AccountSet, bad_inputs)
-    TEST_F(MutexMakeTest, default_constructor)
-    TEST(SHAMap, DISABLED_slow_path)
-    """
-    assert reports(code) == []
-    assert fixed(code) == dedent(code)
-
-
-def test_lookalikes_ignored() -> None:
-    code = """
-    // TEST(Suite, notATest)
-    TEST_EXPECT(someCall())
-    TEST_EXPECTS(amount == value, amount.getText())
-    INSTANTIATE_TEST_SUITE_P(Prefix, Fixture, testValues());
-    auto x = TEST(Suite, notATest);
-    TYPED_TEST_SUITE(Fixture, MyTypes);
-    """
-    assert reports(code) == []
-    assert fixed(code) == dedent(code)
-
-
-def test_indented_and_wrapped_definitions() -> None:
-    code = """
-    namespace ripple {
-        TEST(Suite, indentedName)
-    }
-    TEST_F(
-        SomeVeryLongFixtureName,
-        wrappedName)
-    """
-    assert fixed(code) == dedent("""
-        namespace ripple {
-            TEST(Suite, indented_name)
-        }
-        TEST_F(
-            SomeVeryLongFixtureName,
-            wrapped_name)
-        """)
-
-
-# --- rewriting --------------------------------------------------------------
-
-
-def test_only_the_two_names_are_rewritten() -> None:
-    code = """
-    TEST(mulDiv, mulDiv)
-    {
-        auto const mulDiv = 1;  // mulDiv stays
-    }
-    """
-    assert fixed(code) == dedent("""
-        TEST(MulDiv, mul_div)
-        {
-            auto const mulDiv = 1;  // mulDiv stays
-        }
-        """)
-
-
-def test_suite_name_camel_cased() -> None:
-    code = """
-    TEST(json_value, limits)
-    TEST(scope, ScopeExit)
-    """
-    assert reports(code) == [
-        "1: renamed suite 'json_value' to 'JsonValue'",
-        "2: renamed suite 'scope' to 'Scope'",
-        "2: renamed test case 'ScopeExit' to 'scope_exit'",
-    ]
-    assert fixed(code) == dedent("""
-        TEST(JsonValue, limits)
-        TEST(Scope, scope_exit)
-        """)
-
-
-def test_fixture_reported_but_not_renamed() -> None:
-    # The first argument names a class, so only a human (or clang-tidy) can
-    # rename it; the test-case name is still fixed.
-    code = """
-    TEST_F(my_fixture, someTest)
-    """
-    assert reports(code) == [
-        "1: fixture 'my_fixture' is not CamelCase: rename the class to "
-        "'MyFixture' by hand",
-        "1: renamed test case 'someTest' to 'some_test'",
-    ]
-    assert fixed(code) == dedent("""
-        TEST_F(my_fixture, some_test)
-        """)
-
-
-def test_reports_carry_line_numbers() -> None:
-    code = """
-    #include <foo.h>
-
-    TEST(Suite, firstName)
-
-    TEST(Suite, secondName)
-    """
-    assert reports(code) == [
-        "3: renamed test case 'firstName' to 'first_name'",
-        "5: renamed test case 'secondName' to 'second_name'",
-    ]
-
-
-# --- collisions -------------------------------------------------------------
-
-
-def test_collision_reported_and_not_applied() -> None:
-    # Both would define `Suite_mul_div_Test`.
-    code = """
-    TEST(Suite, mulDiv)
-    TEST(Suite, mul_div)
-    """
-    assert reports(code) == [
-        "1: cannot rename 'Suite, mulDiv' to 'Suite, mul_div': another test "
-        "case already generates that name"
-    ]
-    assert fixed(code) == dedent(code)
-
-
-def test_collision_between_converging_suites() -> None:
-    # Both suites camel-case to `SuiteA`, so both would define
-    # `SuiteA_one_test_Test`.
-    code = """
-    TEST(SuiteA, oneTest)
-    TEST(Suite_a, one_test)
-    """
-    assert [r.split(":")[1].strip() for r in reports(code)] == [
-        "cannot rename 'SuiteA, oneTest' to 'SuiteA, one_test'",
-        "cannot rename 'Suite_a, one_test' to 'SuiteA, one_test'",
-    ]
-    assert fixed(code) == dedent(code)
-
-
-def test_same_name_in_different_suites_is_not_a_collision() -> None:
-    code = """
-    TEST(SuiteOne, mulDiv)
-    TEST(SuiteTwo, mulDiv)
-    """
-    assert fixed(code) == dedent("""
-        TEST(SuiteOne, mul_div)
-        TEST(SuiteTwo, mul_div)
-        """)
-
-
-def main() -> int:
-    tests = sorted(
-        (name, fn)
-        for name, fn in globals().items()
-        if name.startswith("test_") and callable(fn)
-    )
-    failed = 0
-    for name, fn in tests:
-        try:
-            fn()
-            print(f"PASS {name}")
-        except AssertionError as exc:
-            failed += 1
-            print(f"FAIL {name}: {exc!r}")
-    print(f"\n{len(tests) - failed}/{len(tests)} passed")
-    return 1 if failed else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

cfg/xrpld-example.cfg

@@ -1094,8 +1094,8 @@
 #                           Default is 100.
 #
 #       back_off_milliseconds
-#                           Number of milliseconds to wait between online_delete
-#                           SQL deletion batches to allow other functions
+#                           Number of milliseconds to wait between
+#                           online_delete batches to allow other functions
 #                           to catch up.
 #                           Default is 100.
 #
@@ -1109,22 +1109,10 @@
 #                           The online delete process checks periodically
 #                           that xrpld is still in sync with the network,
 #                           and that the validated ledger is less than
-#                           'age_threshold_seconds' old, and that all
-#                           recent ledgers are available. If not, then continue
+#                           'age_threshold_seconds' old. If not, then continue
 #                           sleeping for this number of seconds and
 #                           checking until healthy.
-#                           Default is 2.
-#
-#       max_waiting_ledgers
-#                           The maximum number of ledgers that may be validated
-#                           while online deletion is waiting for the node to get
-#                           fully synced with the rest of the network. If more than
-#                           this number of ledgers are validated while waiting, then
-#                           online deletion gives up on the current ledger and tries
-#                           again later. Note this only affects situations that cause
-#                           rotation to wait, such as going out of sync, or missing
-#                           ledgers. Forward progress is not penalized. Minimum is 64.
-#                           Default is the online_delete value.
+#                           Default is 5.
 #
 #   Notes:
 #       The 'node_db' entry configures the primary, persistent storage.

cmake/GitInfo.cmake

@@ -0,0 +1,28 @@
+include_guard()
+
+set(GIT_BUILD_BRANCH "")
+set(GIT_COMMIT_HASH "")
+
+find_package(Git)
+if(NOT Git_FOUND)
+    message(WARNING "Git not found. Git branch and commit hash will be empty.")
+    return()
+endif()
+
+set(GIT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/.git)
+
+execute_process(
+    COMMAND
+        ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse --abbrev-ref HEAD
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    OUTPUT_VARIABLE GIT_BUILD_BRANCH
+)
+
+execute_process(
+    COMMAND ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse HEAD
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    OUTPUT_VARIABLE GIT_COMMIT_HASH
+)
+
+message(STATUS "Git branch: ${GIT_BUILD_BRANCH}")
+message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")

cmake/XrplCompiler.cmake

@@ -120,10 +120,7 @@ if(MSVC)
             _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
             $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>
     )
-    target_link_libraries(
-        common
-        INTERFACE -errorreport:none -machine:X64 -ignore:4099
-    )
+    target_link_libraries(common INTERFACE -errorreport:none -machine:X64)
 else()
     target_compile_options(
         common
@@ -269,50 +266,10 @@ elseif(use_lld)
     )
     if("${LD_VERSION}" MATCHES "LLD")
         target_link_libraries(common INTERFACE -fuse-ld=lld)
-        # remembered for the linker flag probe below
-        set(fuse_ld_flag "-fuse-ld=lld")
     endif()
     unset(LD_VERSION)
 endif()
 
-# Linker warnings are errors where we control the toolchain and the dependencies: CI and the Nix dev shell.
-# On non-Nix macOS we suppress the deployment target warning: an old Conan profile may not pin os.version.
-# Only the new Apple linker understands the flag, so probe the actual linker (lld may be selected above).
-if(is_macos OR is_linux)
-    if(is_ci OR is_nix_compiler)
-        if(is_macos)
-            set(fatal_warnings_flag "-Wl,-fatal_warnings")
-        else()
-            set(fatal_warnings_flag "-Wl,--fatal-warnings")
-        endif()
-        message(
-            STATUS
-            "Treating all linker warnings as errors (${fatal_warnings_flag})"
-        )
-        target_link_options(common INTERFACE "${fatal_warnings_flag}")
-        unset(fatal_warnings_flag)
-    elseif(is_macos)
-        set(silence_flag "-Wl,-deployment_target_mismatches,suppress")
-        set(probe_flags ${fuse_ld_flag} "${silence_flag}")
-        include(CheckLinkerFlag)
-        check_linker_flag(
-            CXX
-            "${probe_flags}"
-            have_deployment_target_mismatches
-        )
-        if(have_deployment_target_mismatches)
-            message(
-                STATUS
-                "Silencing macOS deployment target mismatch warnings (${silence_flag})"
-            )
-            target_link_options(common INTERFACE "${silence_flag}")
-        endif()
-        unset(probe_flags)
-        unset(silence_flag)
-    endif()
-endif()
-unset(fuse_ld_flag)
-
 if(assert)
     foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
         string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")

cmake/XrplCore.cmake

@@ -51,8 +51,6 @@ target_compile_options(
 
 target_link_libraries(xrpl.libpb PUBLIC protobuf::libprotobuf gRPC::grpc++)
 
-add_dependencies(tidy_prerequisites xrpl.libpb)
-
 # TODO: Clean up the number of library targets later.
 add_library(xrpl.imports.main INTERFACE)
 
@@ -81,7 +79,7 @@ include(target_link_modules)
 add_module(xrpl beast)
 target_link_libraries(xrpl.libxrpl.beast PUBLIC xrpl.imports.main)
 
-include(XrplVersion)
+include(GitInfo)
 add_module(xrpl git)
 target_compile_definitions(
     xrpl.libxrpl.git
@@ -111,11 +109,6 @@ target_link_libraries(
     xrpl.libxrpl.protocol
     PUBLIC xrpl.libxrpl.crypto xrpl.libxrpl.git xrpl.libxrpl.json
 )
-# Only on BuildInfo.cpp, so a new version does not rebuild the whole module.
-set_source_files_properties(
-    ${CMAKE_CURRENT_SOURCE_DIR}/src/libxrpl/protocol/BuildInfo.cpp
-    PROPERTIES COMPILE_DEFINITIONS XRPLD_VERSION="${XRPLD_VERSION}"
-)
 
 # Level 05
 add_module(xrpl protocol_autogen)
@@ -212,7 +205,17 @@ target_link_libraries(
 )
 
 add_module(xrpl tx)
-target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)
+# The wasm engine is a Rust crate reached over cxx: the bridge target supplies the
+# generated `lib.h` and `rust/cxx.h` that `tx/wasm` compiles against, and the Rust
+# static library everything downstream links. PUBLIC because the include path travels
+# with the module's own public headers.
+target_link_libraries(
+    xrpl.libxrpl.tx
+    PUBLIC xrpl.libxrpl.ledger xrpl_wasm_vm_ffi_cxxbridge
+)
+# Those headers do not exist at configure time, and the header-verification target
+# compiles this module's headers on their own, so both need the crates built first.
+add_dependencies(xrpl.libxrpl.tx xrpl_crates)
 
 add_module(xrpl consensus)
 target_link_libraries(
@@ -301,14 +304,7 @@ if(xrpld)
         target_sources(xrpld PRIVATE ${sources})
     endif()
 
-    target_link_libraries(
-        xrpld
-        Xrpl::boost
-        Xrpl::opts
-        Xrpl::libs
-        xrpl.libxrpl
-        rpcspec::rpcspec
-    )
+    target_link_libraries(xrpld Xrpl::boost Xrpl::opts Xrpl::libs xrpl.libxrpl)
     exclude_if_included(xrpld)
     # define a macro for tests that might need to
     # be excluded or run differently in CI environment

cmake/XrplCov.cmake

@@ -44,11 +44,10 @@ setup_target_for_coverage_gcovr(
     EXCLUDE
         "src/test"
         "src/tests"
-        "src/benchmarks"
         "include/xrpl/beast/test"
         "include/xrpl/beast/unit_test"
         "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"
-    DEPENDENCIES xrpld xrpl_tests xrpld_tests
+    DEPENDENCIES xrpld xrpl_tests
 )
 
 add_code_coverage_to_target(opts INTERFACE)

cmake/XrplPackaging.cmake

@@ -1,7 +1,7 @@
 #[===================================================================[
    Linux packaging support: 'package' target.
 
-   The packaging script (package/build_pkg.py) installs to FHS-standard
+   The packaging script (package/build_pkg.sh) installs to FHS-standard
    paths (/usr/bin, /etc/xrpld, etc.) regardless of CMAKE_INSTALL_PREFIX,
    so no prefix guard is needed here.
 #]===================================================================]
@@ -38,26 +38,19 @@ if(NOT TARGET validator-keys)
     return()
 endif()
 
-if(DPKG_BUILDPACKAGE_EXECUTABLE)
-    set(pkg_type deb)
-else()
-    set(pkg_type rpm)
-endif()
-
-# Unquoted below, so an empty value adds no argument at all.
-set(pkg_variant_option "")
-if(assert)
-    set(pkg_variant_option --variant=assert)
-endif()
+set(package_env
+    SRC_DIR=${CMAKE_SOURCE_DIR}
+    BUILD_DIR=${CMAKE_BINARY_DIR}
+    PKG_RELEASE=${pkg_release}
+)
 
 add_custom_target(
     package
     COMMAND
-        ${CMAKE_SOURCE_DIR}/package/build_pkg.py --package-type=${pkg_type}
-        --build-dir=${CMAKE_BINARY_DIR} --pkg-release=${pkg_release}
-        ${pkg_variant_option} --channel=UNRELEASED
+        ${CMAKE_COMMAND} -E env ${package_env}
+        ${CMAKE_SOURCE_DIR}/package/build_pkg.sh
     WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
     DEPENDS xrpld validator-keys
-    COMMENT "Building Linux ${pkg_type} package"
+    COMMENT "Building Linux package (deb/rpm inferred from host tooling)"
     VERBATIM
 )

cmake/XrplSettings.cmake

@@ -32,11 +32,6 @@ endif()
 
 option(benchmark "Build benchmarks" ON)
 
-# When OFF, the crates directory is not added to the build at all: no Rust
-# toolchain is required, no cxxbridge bindings are generated, and the C++ tests
-# that consume those bindings are left out of the build tree.
-option(rust "Build the Rust crates and the C++ code that depends on them" OFF)
-
 # 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

cmake/XrplVersion.cmake

@@ -1,75 +1,15 @@
-find_package(Git)
+#[===================================================================[
+   read version from source
+#]===================================================================]
 
-set(GIT_BUILD_BRANCH "")
-set(GIT_COMMIT_HASH "")
-
-if(DEFINED ENV{GITHUB_BRANCH_NAME})
-    set(GIT_BUILD_BRANCH $ENV{GITHUB_BRANCH_NAME})
-    set(GIT_COMMIT_HASH $ENV{GITHUB_HEAD_SHA})
-elseif(Git_FOUND AND EXISTS "${CMAKE_CURRENT_LIST_DIR}/../.git")
-    execute_process(
-        COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref HEAD
-        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/..
-        OUTPUT_VARIABLE GIT_BUILD_BRANCH
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        COMMAND_ERROR_IS_FATAL ANY
-    )
-
-    execute_process(
-        COMMAND ${GIT_EXECUTABLE} rev-parse HEAD
-        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/..
-        OUTPUT_VARIABLE GIT_COMMIT_HASH
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        COMMAND_ERROR_IS_FATAL ANY
-    )
-endif()
-
-message(STATUS "Git branch: ${GIT_BUILD_BRANCH}")
-message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")
-
-if(
-    DEFINED ENV{FORCE_XRPLD_VERSION}
-    AND NOT "$ENV{FORCE_XRPLD_VERSION}" STREQUAL ""
-)
-    message(
-        STATUS
-        "Using explicitly provided '$ENV{FORCE_XRPLD_VERSION}' as xrpld version"
-    )
-
-    set(XRPLD_VERSION "$ENV{FORCE_XRPLD_VERSION}")
-
-    # The rules beast::SemanticVersion::parse applies, so that an invalid version
-    # fails here rather than when xrpld starts. It reads each number as an int.
-    set(SEMVER_NUMBER "(0|[1-9][0-9]*)")
-    set(SEMVER_PRE_RELEASE "[A-Za-z1-9-][A-Za-z0-9-]*")
-    set(SEMVER_METADATA "[A-Za-z0-9-]+")
-    set(SEMVER_NUMBER_MAX 2147483647)
-    if(
-        NOT XRPLD_VERSION
-            MATCHES
-            "^${SEMVER_NUMBER}\\.${SEMVER_NUMBER}\\.${SEMVER_NUMBER}(-${SEMVER_PRE_RELEASE}(\\.${SEMVER_PRE_RELEASE})*)?(\\+${SEMVER_METADATA}(\\.${SEMVER_METADATA})*)?$"
-        OR CMAKE_MATCH_1 GREATER SEMVER_NUMBER_MAX
-        OR CMAKE_MATCH_2 GREATER SEMVER_NUMBER_MAX
-        OR CMAKE_MATCH_3 GREATER SEMVER_NUMBER_MAX
-    )
-        message(
-            FATAL_ERROR
-            "FORCE_XRPLD_VERSION '${XRPLD_VERSION}' is not a semantic version xrpld accepts, see https://semver.org"
-        )
+file(STRINGS src/libxrpl/protocol/BuildInfo.cpp BUILD_INFO)
+foreach(line_ ${BUILD_INFO})
+    if(line_ MATCHES "versionString[ ]*=[ ]*\"(.+)\"")
+        set(xrpld_version ${CMAKE_MATCH_1})
     endif()
+endforeach()
+if(xrpld_version)
+    message(STATUS "xrpld version: ${xrpld_version}")
 else()
-    message(STATUS "Using '0.0.0-dev+<git short rev>' as xrpld version")
-
-    if(GIT_COMMIT_HASH STREQUAL "")
-        message(
-            FATAL_ERROR
-            "Unable to determine xrpld version without git, set FORCE_XRPLD_VERSION"
-        )
-    endif()
-
-    string(SUBSTRING ${GIT_COMMIT_HASH} 0 7 GIT_COMMIT_HASH_SHORT)
-
-    set(XRPLD_VERSION "0.0.0-dev+${GIT_COMMIT_HASH_SHORT}")
+    message(FATAL_ERROR "unable to determine xrpld version")
 endif()
-
-message(STATUS "Build version: ${XRPLD_VERSION}")

cmake/scripts/codegen/generate_tx_classes.py

@@ -8,7 +8,6 @@ Uses pcpp to preprocess the macro file and pyparsing to parse the DSL.
 
 import io
 import argparse
-import re
 from pathlib import Path
 import pyparsing as pp
 
@@ -54,89 +53,28 @@ def create_transaction_parser():
     return macro_parser
 
 
-# Defaults for xrpl::TxSettings members, mirroring
-# include/xrpl/protocol/TxSettings.h. A transaction's settings blob only names
-# the members that differ from these.
-SETTING_DEFAULTS = {
-    "delegable": "Delegation::NotDelegable",
-    "amendment": "UInt256{}",
-    "privileges": "Privilege::NoPriv",
-}
-
-
-def parse_settings(settings_str):
-    """Parse a TxSettings blob into a dict, filling in defaults.
-
-    Args:
-        settings_str: A string like '({.delegable = Delegation::NotDelegable,
-                      .privileges = Privilege::CreateAcct})', or '({})'.
-
-    Returns:
-        A dict with a value for every key in SETTING_DEFAULTS.
-    """
-    body = settings_str.strip()
-    if not (body.startswith("(") and body.endswith(")")):
-        raise ValueError(
-            f"Malformed settings blob, expected '({{...}})': {settings_str!r}"
-        )
-    body = body[1:-1].strip()
-    if not (body.startswith("{") and body.endswith("}")):
-        raise ValueError(
-            f"Malformed settings blob, expected '({{...}})': {settings_str!r}"
-        )
-    body = body[1:-1]
-
-    # Strip comments, which may be interleaved with the designated initializers.
-    body = re.sub(r"//[^\n]*", "", body)
-
-    settings = dict(SETTING_DEFAULTS)
-    seen = set()
-    # Each entry runs from '.key =' up to the next '.key =' or the end.
-    for key, value in re.findall(
-        r"\.(\w+)\s*=\s*(.*?)(?=,\s*\.\w+\s*=|,?\s*$)", body, re.S
-    ):
-        if key not in SETTING_DEFAULTS:
-            raise ValueError(f"Unknown TxSettings member '.{key}' in {settings_str!r}")
-        settings[key] = " ".join(value.split()).rstrip(",")
-        seen.add(key)
-
-    # Catch a typo'd or unparsed initializer rather than silently defaulting it.
-    # Every '.member' in the blob must have been consumed above.
-    if len(re.findall(r"\.\w+", body)) != len(seen):
-        raise ValueError(f"Could not parse every setting in {settings_str!r}")
-
-    # A blob with content but no designated initializer is positional, which
-    # would otherwise be read as "all defaults" and silently generate the
-    # wrong output.
-    if body.strip() and not seen:
-        raise ValueError(
-            "TxSettings requires designated initializers (.member = value), "
-            f"got {settings_str!r}"
-        )
-
-    return settings
-
-
 def parse_transaction_args(args_list):
     """Parse the arguments of a TRANSACTION macro call.
 
     Args:
         args_list: A list of parsed arguments from pyparsing, e.g.,
-                   ['ttPAYMENT', '0', 'Payment',
-                    '({.privileges = Privilege::CreateAcct})', '({...})']
+                   ['ttPAYMENT', '0', 'Payment', 'Delegation::delegable',
+                    'uint256{}', 'createAcct', '({...})']
 
     Returns:
         A dict with parsed transaction information.
     """
-    if len(args_list) < 5:
+    if len(args_list) < 7:
         raise ValueError(
-            f"Expected at least 5 parts in TRANSACTION, got {len(args_list)}: {args_list}"
+            f"Expected at least 7 parts in TRANSACTION, got {len(args_list)}: {args_list}"
         )
 
     tag = args_list[0]
     value = args_list[1]
     name = args_list[2]
-    settings = parse_settings(args_list[3])
+    delegable = args_list[3]
+    amendments = args_list[4]
+    privileges = args_list[5]
     fields_str = args_list[-1]
 
     # Parse fields: ({field1, field2, ...})
@@ -146,9 +84,9 @@ def parse_transaction_args(args_list):
         "tag": tag,
         "value": value,
         "name": name,
-        "delegable": settings["delegable"],
-        "amendments": settings["amendment"],
-        "privileges": settings["privileges"],
+        "delegable": delegable,
+        "amendments": amendments,
+        "privileges": privileges,
         "fields": fields,
     }
 

cmake/scripts/codegen/templates/LedgerEntry.h.mako

@@ -209,7 +209,7 @@ ${field['typeData']['setter_type']} ${field['paramName']}${',' if i < len(requir
      * @return The constructed ledger entry wrapper.
      */
     ${name}
-    build(UInt256 const& index)
+    build(uint256 const& index)
     {
         return ${name}{std::make_shared<SLE>(std::move(object_), index)};
     }

cmake/scripts/codegen/templates/LedgerEntryTests.cpp.mako

@@ -31,7 +31,7 @@ namespace xrpl::ledger_entries {
 // builder's STObject and the wrapper's SLE.
 TEST(${name}Tests, BuilderSettersRoundTrip)
 {
-    UInt256 const index{1u};
+    uint256 const index{1u};
 
 % for field in fields:
     auto const ${field["paramName"]}Value = ${canonical_expr(field)};
@@ -85,7 +85,7 @@ TEST(${name}Tests, BuilderSettersRoundTrip)
 // from that SLE, build a new wrapper, and verify all fields (and validate()).
 TEST(${name}Tests, BuilderFromSleRoundTrip)
 {
-    UInt256 const index{2u};
+    uint256 const index{2u};
 
 % for field in fields:
     auto const ${field["paramName"]}Value = ${canonical_expr(field)};
@@ -146,7 +146,7 @@ TEST(${name}Tests, BuilderFromSleRoundTrip)
 // 3) Verify wrapper throws when constructed from wrong ledger entry type.
 TEST(${name}Tests, WrapperThrowsOnWrongEntryType)
 {
-    UInt256 const index{3u};
+    uint256 const index{3u};
 
     // Build a valid ledger entry of a different type
     // Ticket requires: Account, OwnerNode, TicketSequence, PreviousTxnID, PreviousTxnLgrSeq
@@ -177,7 +177,7 @@ TEST(${name}Tests, WrapperThrowsOnWrongEntryType)
 // 4) Verify builder throws when constructed from wrong ledger entry type.
 TEST(${name}Tests, BuilderThrowsOnWrongEntryType)
 {
-    UInt256 const index{4u};
+    uint256 const index{4u};
 
     // Build a valid ledger entry of a different type
 % if wrong_le_include == "Ticket":
@@ -207,7 +207,7 @@ TEST(${name}Tests, BuilderThrowsOnWrongEntryType)
 // 5) Build with only required fields and verify optional fields return nullopt.
 TEST(${name}Tests, OptionalFieldsReturnNullopt)
 {
-    UInt256 const index{3u};
+    uint256 const index{3u};
 
 % for field in required_fields:
     auto const ${field["paramName"]}Value = ${canonical_expr(field)};

conan.lock

@@ -3,7 +3,6 @@
     "requires": [
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
         "xxhash/0.8.3#681d36a0a6111fc56e5e45ea182c19cc%1782392402.420688",
-        "xrpl-rpc-spec/0.1.19#870b2d3abcfbbf13b61c2d3c69495060%1790348286.187549",
         "sqlite3/3.53.0#324ada52333108388a9a6108bfa96734%1782392403.185447",
         "soci/4.0.3#e726491a03468795453f7c83fc924a96%1782392402.679521",
         "snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1782307151.633168",
@@ -20,11 +19,10 @@
         "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#b87796a4269034856cbc1a2522db16eb%1788275071.530512",
-        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1785888854.601666",
+        "grpc/1.81.1#f729f6d75992d20f9c72828e9142d62f%1783945160.094135",
+        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1782494504.298",
         "ed25519/2015.03#ae761bdc52730a843f0809bdf6c1b1f6%1782307148.15562",
         "date/3.0.4#862e11e80030356b53c2c38599ceb32b%1782392402.538492",
-        "corrosion/0.6.1#bfa292df0a957bc70a450ff316cd9435%1786119416.131296",
         "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1782392402.681654",
         "bzip2/1.0.8#c470882369c2d95c5c77e970c0c7e321%1782392402.296732",
         "boost/1.91.0#ea540ca2133d831b560036aa24dece3c%1782392419.475605",
@@ -46,10 +44,6 @@
     ],
     "python_requires": [],
     "overrides": {
-        "boost/1.91.0#ea540ca2133d831b560036aa24dece3c": [
-            null,
-            "boost/1.91.0#ea540ca2133d831b560036aa24dece3c"
-        ],
         "protobuf/[>=5.27.0 <7]": [
             "protobuf/6.33.5"
         ],

conan/init.sh

@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-# Install our Conan configuration, profiles and the xrplf remote into CONAN_HOME.
-# Safe to re-run; never deletes the Conan home.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-CONAN_DIR="$(conan config home)"
-
-echo "Installing Conan configuration into ${CONAN_DIR}"
-conan config install "${SCRIPT_DIR}/global.conf"
-conan config install "${SCRIPT_DIR}/profiles" -tf "${CONAN_DIR}/profiles"
-# This script manages these files, so make them read-only - Conan does not
-# preserve the source mode. Only the files: the directories must stay writable
-# for `conan config install` to replace them.
-chmod a-w "${CONAN_DIR}/global.conf"
-find "${CONAN_DIR}/profiles" -type f -exec chmod a-w {} +
-
-echo "Adding the xrplf Conan remote"
-# --index 0: our patched recipes must win over Conan Center.
-conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/

conan/profiles/default

@@ -1,7 +1,10 @@
 {% set os = detect_api.detect_os() %}
 {% set arch = detect_api.detect_arch() %}
 {% set compiler, version, compiler_exe = detect_api.detect_default_compiler() %}
+{% set compiler_version = version %}
+{% if os == "Linux" %}
 {% set compiler_version = detect_api.default_compiler_version(compiler, version) %}
+{% endif %}
 {% if os == "Macos" %}
 {# Minimum macOS the dependencies target. #}
 {# Without this, Conan builds each dependency against the (possibly newer) host SDK, so the #}

conanfile.py

@@ -1,13 +1,9 @@
-import os
 import re
 
 from conan.tools.cmake import CMake, CMakeToolchain, cmake_layout
-from conan.tools.env import Environment
 
 from conan import ConanFile
 
-DEV_VERSION = "0.0.0-dev"
-
 
 class Xrpl(ConanFile):
     name = "xrpl"
@@ -32,7 +28,6 @@ class Xrpl(ConanFile):
     }
 
     requires = [
-        "corrosion/0.6.1",
         "ed25519/2015.03",
         "fast_float/8.2.10",
         "grpc/1.81.1",
@@ -40,7 +35,6 @@ class Xrpl(ConanFile):
         "nudb/2.0.9",
         "openssl/3.6.3",
         "soci/4.0.3",
-        "xrpl-rpc-spec/0.1.19",
         "zlib/1.3.2",
     ]
 
@@ -119,12 +113,17 @@ class Xrpl(ConanFile):
         "soci/*:shared": False,
         "soci/*:with_sqlite3": True,
         "soci/*:with_boost": True,
-        "xrpl-rpc-spec/*:server": "xrpld",
         "xxhash/*:shared": False,
     }
 
     def set_version(self):
-        self.version = self.version or DEV_VERSION
+        if self.version is None:
+            path = f"{self.recipe_folder}/src/libxrpl/protocol/BuildInfo.cpp"
+            regex = r"versionString\s?=\s?\"(.*)\""
+            with open(path, encoding="utf-8") as file:
+                matches = (re.search(regex, line) for line in file)
+                match = next(m for m in matches if m)
+                self.version = match.group(1)
 
     def configure(self):
         if self.settings.compiler == "apple-clang":
@@ -149,7 +148,6 @@ class Xrpl(ConanFile):
         self.requires("xxhash/0.8.3", transitive_headers=True)
 
     exports_sources = (
-        "bin/default-loader-path.sh",
         "CMakeLists.txt",
         "cfg/*",
         "cmake/*",
@@ -167,17 +165,6 @@ class Xrpl(ConanFile):
     generators = "CMakeDeps"
 
     def generate(self):
-        # The sources in the Conan cache have no git history, so the version
-        # comes from the reference, unless it is not one, like 'develop'.
-        if not os.path.exists(os.path.join(self.source_folder, ".git")):
-            version = str(self.version)
-            env = Environment()
-            env.define(
-                "FORCE_XRPLD_VERSION",
-                version if re.match(r"\d+\.\d+\.\d+", version) else DEV_VERSION,
-            )
-            env.vars(self).save_script("xrpld_version")
-
         tc = CMakeToolchain(self)
         tc.variables["tests"] = self.options.tests
         tc.variables["benchmark"] = self.options.benchmark

crates/.cargo/config.toml

@@ -1,17 +1,5 @@
-# The Rust static libraries are linked into C++ targets, so the runtime linkage
-# here has to match what the C++ build uses (see cmake/XrplCompiler.cmake).
-#
-# macOS needs nothing: AppleClang cannot link libgcc/libc++ statically, so the
-# C++ build skips those flags on Apple as well.
-
-# Both amd64 and arm64 Linux builds link libgcc statically. This only affects
-# links that rustc itself drives (`cargo test` binaries and the like) — the
-# `staticlib` crates consumed by CMake are archived, not linked, so rustc
-# silently ignores link args for them. Keeping libgcc_s.so.1 off the xrpld link
-# line is handled in crates/CMakeLists.txt instead.
-[target.'cfg(target_os = "linux")']
+[target.x86_64-unknown-linux-gnu]
 rustflags = ["-C", "link-args=-static-libgcc"]
 
-# Windows builds use the static MSVC runtime.
-[target.'cfg(windows)']
+[target.x86_64-pc-windows-msvc]
 rustflags = ["-C", "target-feature=+crt-static"]

crates/CMakeLists.txt

@@ -1,90 +1,37 @@
-find_package(Corrosion REQUIRED)
+set(CORROSION_VERSION 0.6.1)
+
+find_package(Corrosion ${CORROSION_VERSION} QUIET)
+if(NOT Corrosion_FOUND)
+    include(FetchContent)
+    FetchContent_Declare(
+        Corrosion
+        GIT_REPOSITORY https://github.com/corrosion-rs/corrosion.git
+        GIT_TAG v${CORROSION_VERSION}
+    )
+    FetchContent_MakeAvailable(Corrosion)
+endif()
 
 corrosion_import_crate(MANIFEST_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Cargo.toml)
 
-# The generated C++ lands in the build tree, so put a .clang-tidy next to it to
-# keep clang-tidy from analyzing code we don't own.
-configure_file(
-    generated.clang-tidy
-    "${CMAKE_CURRENT_BINARY_DIR}/.clang-tidy"
-    COPYONLY
+file(
+    WRITE "${CMAKE_CURRENT_BINARY_DIR}/.clang-tidy"
+    "# Auto-generated by crates/CMakeLists.txt. Do not edit.\n"
+    "# Neutralizes clang-tidy for corrosion/cxxbridge-generated C++.\n"
+    "# One check kept enabled to avoid clang-tidy's \"no checks enabled\" error.\n"
+    "Checks: '-*,google-readability-todo'\n"
+    "WarningsAsErrors: ''\n"
+    "HeaderFilterRegex: ''\n"
+    "InheritParentConfig: false\n"
 )
 
+# Umbrella target that aggregates all crate-generated code (cxxbridge headers,
+# etc.). Build this before running clang-tidy so generated headers are present.
 add_custom_target(xrpl_crates)
-add_dependencies(tidy_prerequisites xrpl_crates)
-
-# On macOS, ld warns `ignoring duplicate libraries` when linking a crate.
-# Corrosion is the source of both duplicates it names:
-#
-# * The crate archive and its cxxbridge archive, because
-#   `corrosion_add_cxxbridge` makes the two depend on each other, and CMake
-#   repeats a static library cycle on the link line so single-pass linkers can
-#   resolve it. (LINK_INTERFACE_MULTIPLICITY can only raise that count.)
-# * `-lSystem`, which Corrosion copies from rustc's `native-static-libs` even
-#   though the compiler driver always links libSystem.
-#
-# ld needs neither: it resolves the cycle from one copy of each archive and
-# links libSystem once. So silence the warning rather than rewrite Corrosion's
-# link interface, which the cycle is also part of. The option itself is old —
-# Xcode 15 is only where the warning became the default — and the check below
-# leaves it out on a linker that does not know it.
-if(is_macos)
-    include(CheckLinkerFlag)
-    check_linker_flag(
-        CXX
-        -Wl,-no_warn_duplicate_libraries
-        have_no_warn_duplicate_libraries
-    )
-endif()
-
-function(_unlink_libgcc_s crate)
-    if(NOT (is_linux AND static))
-        return()
-    endif()
-
-    # Corrosion exposes a crate's staticlib as an imported `<crate>-static`
-    # target and puts the native libs in its INTERFACE_LINK_LIBRARIES. If either
-    # of those changes, warn instead of silently letting libgcc_s.so.1 return.
-    set(imported "${crate}-static")
-    if(NOT TARGET ${imported})
-        message(
-            FATAL_ERROR
-            "Corrosion did not create the imported target '${imported}', so "
-            "libgcc_s cannot be removed from the link interface of '${crate}'. "
-            "xrpld will link libgcc_s.so.1 dynamically. Check where Corrosion "
-            "${CORROSION_VERSION} now records `native-static-libs`."
-        )
-        return()
-    endif()
-
-    get_target_property(libs ${imported} INTERFACE_LINK_LIBRARIES)
-    if(NOT "gcc_s" IN_LIST libs)
-        message(
-            WARNING
-            "'gcc_s' was not in the link interface of '${imported}' as "
-            "expected. If the Rust toolchain stopped reporting it this "
-            "workaround is obsolete and can be deleted; otherwise xrpld may "
-            "link libgcc_s.so.1 dynamically. Verify with: "
-            "objdump -p xrpld | grep NEEDED"
-        )
-        return()
-    endif()
-
-    list(REMOVE_ITEM libs gcc_s)
-    set_property(TARGET ${imported} PROPERTY INTERFACE_LINK_LIBRARIES ${libs})
-endfunction()
 
+# add_xrpl_crate(<name> CRATE <crate> FILES <file>...) Creates a cxxbridge
+# target <name>_cxxbridge and registers it with xrpl_crates.
 function(add_xrpl_crate name)
     cmake_parse_arguments(ARG "" "CRATE" "FILES" ${ARGN})
-    _unlink_libgcc_s(${ARG_CRATE})
-    # `cc` picks its runtime flag from `crt-static` alone, so it compiles a
-    # crate's C++ with `-MT`; Debug needs `-MTd` (to match cmake/XrplCompiler.cmake).
-    if(is_msvc)
-        corrosion_set_env_vars(
-            ${ARG_CRATE}
-            "$<$<CONFIG:Debug>:CXXFLAGS=-MTd>"
-        )
-    endif()
     corrosion_add_cxxbridge(${name}_cxxbridge CRATE ${ARG_CRATE} FILES
                             ${ARG_FILES}
     )
@@ -92,13 +39,21 @@ function(add_xrpl_crate name)
     # validates INTERFACE_SOURCES on consuming targets. Clear it to skip the
     # existence check — build-time ordering is enforced by the custom commands.
     set_target_properties(${name}_cxxbridge PROPERTIES INTERFACE_SOURCES "")
-    if(have_no_warn_duplicate_libraries)
-        target_link_options(
-            ${name}_cxxbridge
-            INTERFACE -Wl,-no_warn_duplicate_libraries
-        )
-    endif()
     add_dependencies(xrpl_crates ${name}_cxxbridge)
 endfunction()
 
-add_xrpl_crate(rs_hello_world CRATE rs_hello_world FILES lib.rs)
+add_xrpl_crate(xrpl_wasm_vm_ffi CRATE xrpl_wasm_vm_ffi FILES lib.rs)
+
+# Test-only, and deliberately not part of xrpl_wasm_vm_ffi: it carries the `wat` assembler,
+# which the engine's `wasmi default-features = false` exists to keep out of the consensus
+# path. Linked from src/tests/libxrpl only, so the shipped node cannot contain it.
+add_xrpl_crate(xrpl_wasm_testkit CRATE xrpl_wasm_testkit FILES lib.rs)
+
+# The wasm bridge `include!`s a project header, so its generated translation unit needs
+# the project's include root. Deliberately only that: a header reached from here must
+# stay light enough to compile without the Boost paths this target does not get, which
+# is why `HostContext.h` forward-declares `xrpl::HostFunctions` instead of including it.
+target_include_directories(
+    xrpl_wasm_vm_ffi_cxxbridge
+    PRIVATE ${CMAKE_SOURCE_DIR}/include
+)

crates/Cargo.lock

@@ -8,6 +8,18 @@ version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
 
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
 [[package]]
 name = "cc"
 version = "1.2.61"
@@ -57,24 +69,24 @@ dependencies = [
 
 [[package]]
 name = "cxx"
-version = "1.0.202"
+version = "1.0.198"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "13f6de320895f42e6e081abb5c7983bedcf0b6d0ff9323de0d33f620c8ac1199"
+checksum = "6fe442a792c7c736eea18b32a7f8a3b63cf8aafabda6760042dc2fdeda456291"
 dependencies = [
  "cc",
  "cxx-build",
  "cxxbridge-cmd",
  "cxxbridge-flags",
  "cxxbridge-macro",
- "foldhash",
+ "foldhash 0.2.0",
  "link-cplusplus",
 ]
 
 [[package]]
 name = "cxx-build"
-version = "1.0.202"
+version = "1.0.198"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fde53ca86b9704a943fef0f1e1d836239a6aedca5de3c65fa9f97ec0bd46d39"
+checksum = "e3184a94384c663718698311a78a51ac00c484c10b4eeac06fb0a068c5f64fa2"
 dependencies = [
  "cc",
  "codespan-reporting",
@@ -87,9 +99,9 @@ dependencies = [
 
 [[package]]
 name = "cxxbridge-cmd"
-version = "1.0.202"
+version = "1.0.198"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bae89236c811fd4d08ed3441759ac4ac98d752cbfd3de341315ba16ad20ec3"
+checksum = "0148d8fd1199329ddf1d157a5e134e51ceff37c6a7ddd38615c399d81cb05d8d"
 dependencies = [
  "clap",
  "codespan-reporting",
@@ -101,15 +113,15 @@ dependencies = [
 
 [[package]]
 name = "cxxbridge-flags"
-version = "1.0.202"
+version = "1.0.198"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49045042e5fced01b80742aba5508de82aa4f13677ed3fa2b4cda709c40c5918"
+checksum = "52850339faed2eaadd24e286dc1d8268cc6f8a7bd9524d713adc9099566b4c89"
 
 [[package]]
 name = "cxxbridge-macro"
-version = "1.0.202"
+version = "1.0.198"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b181252e2e3d3b5d183afbdc033a3958b445eb3e1a0ae65fc3d4f5259f5da6fd"
+checksum = "2c77c856545d886c9bd5215409ebb63b925e262135248b50c79e5a5f194ee47c"
 dependencies = [
  "indexmap",
  "proc-macro2",
@@ -129,12 +141,27 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.0"
@@ -148,9 +175,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown",
+ "hashbrown 0.17.0",
 ]
 
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "link-cplusplus"
 version = "1.0.12"
@@ -160,6 +199,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -178,19 +223,18 @@ dependencies = [
  "proc-macro2",
 ]
 
-[[package]]
-name = "rs-hello_world"
-version = "0.1.0"
-dependencies = [
- "cxx",
-]
-
 [[package]]
 name = "scratch"
 version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d68f2ec51b097e4c1a75b681a8bec621909b5e91f15bb7b840c4f2f7b01148b2"
 
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -227,6 +271,22 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "spin"
+version = "0.9.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
+
+[[package]]
+name = "string-interner"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"
+dependencies = [
+ "hashbrown 0.15.5",
+ "serde",
+]
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -276,6 +336,99 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 
+[[package]]
+name = "wasm-encoder"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09480d646178e5fdd12bb06e812d0af9a3a191dbc9cd697fdc86687beade7393"
+dependencies = [
+ "leb128fmt",
+ "wasmparser 0.254.0",
+]
+
+[[package]]
+name = "wasmi"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2300d0f78cba12f14e29e8dd157ea64050c0a688179aefdb2050105805594a0c"
+dependencies = [
+ "spin",
+ "wasmi_collections",
+ "wasmi_core",
+ "wasmi_ir",
+ "wasmparser 0.239.0",
+]
+
+[[package]]
+name = "wasmi_collections"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8a8c42a2a76148d43097b1d7cc2a5bf33d5c23bd4dd69015fc887e311767884"
+dependencies = [
+ "string-interner",
+]
+
+[[package]]
+name = "wasmi_core"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9013136083d988725953390bf668b64b7a218fabf26f8b913bbc59546b97ee27"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "wasmi_ir"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba1fa003f79156f406d62ef0e1464dc03e11ace37170e9fa7524299a75ad8f68"
+dependencies = [
+ "wasmi_core",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.239.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c9d90bb93e764f6beabf1d02028c70a2156a6583e63ac4218dd07ef733368b0"
+dependencies = [
+ "bitflags",
+ "indexmap",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5769a29f799fbab136aaf65b4fe5384cd7d93fe6fc9ba0dcb6c8382a1f16e27"
+dependencies = [
+ "bitflags",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "wast"
+version = "254.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7ed4dfc8f6b9fc38b231065e2cdfbf7359af5ab945990abf09658dcc63c3e32"
+dependencies = [
+ "bumpalo",
+ "leb128fmt",
+ "memchr",
+ "unicode-width",
+ "wasm-encoder",
+]
+
+[[package]]
+name = "wat"
+version = "1.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7127f7f9b8f127c879991cecd35f494e4628bae1b0874c681414d8d8831e952c"
+dependencies = [
+ "wast",
+]
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -299,3 +452,46 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
  "windows-link",
 ]
+
+[[package]]
+name = "xrpl-host-functions"
+version = "0.1.0"
+dependencies = [
+ "xrpl-host-functions-macros",
+]
+
+[[package]]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-testkit"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "wat",
+]
+
+[[package]]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+dependencies = [
+ "wasmi",
+ "wat",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-vm-ffi"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "xrpl-host-functions",
+ "xrpl-wasm-vm",
+]

crates/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["hello_world"]
+members = ["xrpl-wasm-vm-ffi", "xrpl-wasm-vm", "xrpl-wasm-testkit", "xrpl-host-functions", "xrpl-host-functions-macros"]
 resolver = "3"
 
 [workspace.dependencies]
@@ -8,9 +8,6 @@ cxx = { version = "1.0.198", features = ["c++20"] }
 [workspace.package]
 edition = "2024"
 
-[workspace.lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = [ 'cfg(coverage)', 'cfg(coverage_nightly)' ] }
-
 [profile.release]
 opt-level = 3
 overflow-checks = true

crates/generated.clang-tidy

@@ -1,10 +0,0 @@
----
-# Neutralizes clang-tidy for the corrosion/cxxbridge-generated C++. Copied into
-# the crates build directory by crates/CMakeLists.txt, next to the generated
-# sources, so clang-tidy picks it up instead of the top-level configuration.
-#
-# One check is kept enabled to avoid clang-tidy's "no checks enabled" error.
-Checks: "-*,google-readability-todo"
-WarningsAsErrors: ""
-HeaderFilterRegex: ""
-InheritParentConfig: false

crates/hello_world/src/lib.rs

@@ -1,23 +0,0 @@
-#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
-
-#[cxx::bridge(namespace = "rs::hello_world")]
-mod ffi {
-    extern "Rust" {
-        fn hello_world() -> String;
-    }
-}
-
-pub fn hello_world() -> String {
-    "hello_world".to_string()
-}
-
-#[cfg(test)]
-#[cfg_attr(coverage_nightly, coverage(off))]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn hello_world_returns_hello_world() {
-        assert_eq!(hello_world(), "hello_world")
-    }
-}

crates/xrpl-host-functions-macros/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+syn = { version = "3", features = ["full"] }
+quote = "1"
+proc-macro2 = "1"
+
+# The expansion names `::xrpl_host_functions::HostFnSpec`, so the doctest needs the
+# facade crate. Cargo allows this cycle because dev-dependencies are outside the
+# library build graph.
+[dev-dependencies]
+xrpl-host-functions.path = "../xrpl-host-functions"

crates/xrpl-host-functions-macros/src/errors.rs

@@ -0,0 +1,12 @@
+/// Folds accumulated diagnostics into the single error a macro can return.
+///
+/// `syn::Error` is itself a collection: `combine` appends, and
+/// `into_compile_error` emits one `compile_error!` per recorded span. Folding
+/// instead of returning the first error means every mistake in a
+/// `host_functions!` block surfaces in one build rather than one per rebuild.
+pub(crate) fn combine(errors: Vec<syn::Error>) -> Option<syn::Error> {
+    errors.into_iter().reduce(|mut first, next| {
+        first.combine(next);
+        first
+    })
+}

crates/xrpl-host-functions-macros/src/lib.rs

@@ -0,0 +1,384 @@
+mod errors;
+mod parsed_host_function;
+
+use std::collections::HashSet;
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{
+    TraitItemFn,
+    parse::{Parse, ParseStream},
+    parse2,
+};
+
+use parsed_host_function::ParsedHostFunction;
+
+/// Declares the wasm host ABI once, and generates everything that follows from it.
+///
+/// The input is a block of `fn` declarations, each carrying the gas cost the host
+/// charges before the call and the name the guest imports it under. Doc comments
+/// are kept and appear on the generated items.
+///
+/// This crate is an implementation detail of `xrpl-host-functions`, which
+/// hand-writes the types the expansion refers to and holds the one declaration
+/// block. The expansion names those types by absolute path, so a call site needs
+/// `xrpl-host-functions` as a dependency but no imports from it.
+///
+/// ```
+/// use xrpl_host_functions::HostResult;
+/// use xrpl_host_functions_macros::host_functions;
+///
+/// host_functions! {
+///     /// The sequence number of the ledger being built, as 4 little-endian bytes.
+///     #[gas = 60]
+///     #[wasm_name = "ldgr_index"]
+///     fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+///
+///     /// Writes `msg` to the trace log.
+///     #[gas = 500]
+///     #[wasm_name = "trace_num"]
+///     fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+/// }
+///
+/// // A `HostFunctions` trait, holding the declarations verbatim:
+/// struct Host;
+/// impl HostFunctions for Host {
+///     fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize> {
+///         out[..4].copy_from_slice(&7u32.to_le_bytes());
+///         Ok(4)
+///     }
+///     fn trace_num(&self, _msg: &str, _number: i64) -> HostResult<()> { Ok(()) }
+/// }
+///
+/// // A `HostFunctionSpec` enum carrying the ABI metadata as a `const` table:
+/// assert_eq!(HostFunctionSpec::GetLedgerSqn.gas(), 60);
+/// assert_eq!(HostFunctionSpec::TraceNum.wasm_name(), "trace_num");
+/// assert_eq!(HostFunctionSpec::ALL.len(), 2);
+/// ```
+///
+/// A declaration must be a plain `fn` taking `&self` and returning
+/// `HostResult<T>`, with no body and no generics: it maps to exactly one wasm
+/// import signature. Two declarations may not share a `wasm_name`, nor collapse to
+/// the same PascalCase variant.
+#[proc_macro]
+pub fn host_functions(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    expand(input.into())
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+fn expand(input: TokenStream) -> syn::Result<TokenStream> {
+    let HostFunctionsInput { functions } = parse2(input)?;
+
+    let mut parsed = Vec::with_capacity(functions.len());
+    let mut errors = Vec::new();
+    for function in functions {
+        match ParsedHostFunction::parse(function) {
+            Ok(function) => parsed.push(function),
+            Err(error) => errors.push(error),
+        }
+    }
+    if let Some(error) = errors::combine(errors) {
+        return Err(error);
+    }
+    if let Some(error) = errors::combine(collisions(&parsed)) {
+        return Err(error);
+    }
+
+    Ok(generate(&parsed))
+}
+
+/// Names two declarations may not share, because the generated code would then
+/// fail to compile at a span the caller cannot see.
+fn collisions(functions: &[ParsedHostFunction]) -> Vec<syn::Error> {
+    let mut errors = Vec::new();
+    let mut variants = HashSet::new();
+    let mut wasm_names = HashSet::new();
+
+    for function in functions {
+        if !variants.insert(function.variant.to_string()) {
+            errors.push(syn::Error::new_spanned(
+                &function.variant,
+                format!(
+                    "another host function already becomes the `{}` variant",
+                    function.variant
+                ),
+            ));
+        }
+        if !wasm_names.insert(function.wasm_name.value()) {
+            errors.push(syn::Error::new_spanned(
+                &function.wasm_name,
+                format!(
+                    "another host function is already imported as `{}`",
+                    function.wasm_name.value()
+                ),
+            ));
+        }
+    }
+
+    errors
+}
+
+fn generate(functions: &[ParsedHostFunction]) -> TokenStream {
+    let trait_methods = functions.iter().map(ParsedHostFunction::trait_method);
+    let variants = functions
+        .iter()
+        .map(ParsedHostFunction::variant_declaration);
+    let spec_arms = functions.iter().map(ParsedHostFunction::spec_arm);
+    let all = functions.iter().map(|function| &function.variant);
+
+    quote! {
+        /// The host side of the wasm ABI: one method per function a guest may
+        /// import.
+        ///
+        /// Implement it once per execution environment — the ledger host, a test
+        /// double, a benchmark fake — and a guest module cannot tell them apart.
+        /// Each method is one declaration from the `host_functions!` block, as
+        /// written; its `&self` receiver is not part of the ABI the guest sees,
+        /// so a host that must mutate does so behind interior mutability.
+        ///
+        /// # The output contract
+        ///
+        /// A method handed an `out` buffer **writes into it only when the whole
+        /// value fits, and returns the value's true length whether it fitted or
+        /// not.**
+        ///
+        /// The length is the value's, not the number of bytes written, because it
+        /// is how a guest that asked with too small a buffer learns the size to
+        /// ask for next time. The engine turns a length past the buffer into
+        /// `BufferTooSmall`, and one past the field cap into `DataFieldTooLarge`,
+        /// so a host needs to know neither.
+        ///
+        /// Writing nothing unless the value fits is the half only a host can hold
+        /// up. An engine can bound how many bytes are *writable* — and does, by
+        /// handing over a region clamped to the field cap — but it cannot take
+        /// back what a method already put there. A host that wrote a truncated
+        /// prefix and then reported the larger length would leave those bytes in
+        /// guest memory behind a refusal the guest is told to ignore. C++'s
+        /// `setData` is the reference point: it wrote only on a value that fit.
+        pub trait HostFunctions {
+            #(#trait_methods)*
+        }
+
+        /// One row of the ABI table: what [`HostFunctionSpec::wasm_name`] and
+        /// [`HostFunctionSpec::gas`] read from.
+        ///
+        /// Private, and the only reason it exists is to keep both of them fed
+        /// from a single `match` over the declarations.
+        struct HostFnSpec {
+            name: &'static str,
+            gas: u64,
+        }
+
+        /// Identifies one host function, and is the compile-time source of its
+        /// ABI metadata.
+        ///
+        /// One variant per `host_functions!` declaration, named by converting the
+        /// function name to PascalCase. [`Self::ALL`] is the whole ABI, which is
+        /// what a wasm engine iterates to build its import table.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum HostFunctionSpec {
+            #(#variants,)*
+        }
+
+        impl HostFunctionSpec {
+            /// Every host function, in the order declared.
+            ///
+            /// This is the complete import surface a guest may link against: a
+            /// function absent here cannot be called, and one present here must
+            /// be registered for a module that imports it to instantiate.
+            pub const ALL: &'static [Self] = &[#(Self::#all,)*];
+
+            /// This function's row of the ABI table.
+            const fn spec(self) -> HostFnSpec {
+                match self {
+                    #(#spec_arms,)*
+                }
+            }
+
+            /// The name a guest imports this function under.
+            ///
+            /// A guest's import name must match this exactly, or the module
+            /// fails to instantiate. Usable in `const` context, so import lists
+            /// can be built at compile time.
+            pub const fn wasm_name(self) -> &'static str {
+                self.spec().name
+            }
+
+            /// Gas charged before the call runs, independent of its arguments.
+            ///
+            /// Consensus-relevant: two nodes that disagree on this value
+            /// disagree on transaction outcomes. Usable in `const` context, so
+            /// gas tables can be built at compile time.
+            pub const fn gas(self) -> u64 {
+                self.spec().gas
+            }
+        }
+    }
+}
+
+struct HostFunctionsInput {
+    functions: Vec<TraitItemFn>,
+}
+
+impl Parse for HostFunctionsInput {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let mut functions = Vec::new();
+        while !input.is_empty() {
+            functions.push(input.parse()?);
+        }
+        Ok(HostFunctionsInput { functions })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_an_empty_block() {
+        expand(quote! {}).unwrap();
+    }
+
+    #[test]
+    fn reports_mistakes_from_every_function() {
+        let error = expand(quote! {
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 2000]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; 32]>;
+        })
+        .expect_err("expected parsing to fail");
+
+        let messages: Vec<_> = error.into_iter().map(|error| error.to_string()).collect();
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(messages[0].contains("missing `#[gas"), "{messages:?}");
+        assert!(messages[1].contains("missing `#[wasm_name"), "{messages:?}");
+    }
+
+    #[test]
+    fn propagates_syntax_errors() {
+        let error = expand(quote! { fn missing_semicolon() }).expect_err("expected a syntax error");
+        assert!(!error.to_string().is_empty());
+    }
+
+    /// The messages of every diagnostic recorded by one failed `expand`.
+    fn messages(input: TokenStream) -> Vec<String> {
+        let Err(error) = expand(input) else {
+            panic!("expected expansion to fail");
+        };
+        error.into_iter().map(|error| error.to_string()).collect()
+    }
+
+    #[test]
+    fn generates_the_trait_the_enum_and_the_table() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 500]
+            #[wasm_name = "trace_num"]
+            fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+        })
+        .unwrap()
+        .to_string();
+
+        for expected in [
+            "pub trait HostFunctions",
+            "fn get_ledger_sqn (& self) -> HostResult < [u8 ; 4] > ;",
+            "fn trace_num (& self , msg : & str , number : i64) -> HostResult < () > ;",
+            "pub enum HostFunctionSpec { GetLedgerSqn , TraceNum , }",
+            "pub const ALL : & 'static [Self] = & [Self :: GetLedgerSqn , Self :: TraceNum ,]",
+            // The table's row type is generated too, and stays private.
+            "struct HostFnSpec { name : & 'static str , gas : u64 , }",
+            "const fn spec (self) -> HostFnSpec",
+            "Self :: GetLedgerSqn => HostFnSpec { name : \"ldgr_index\" , gas : 60u64 }",
+            "pub const fn wasm_name (self) -> & 'static str",
+            "pub const fn gas (self) -> u64",
+        ] {
+            assert!(generated.contains(expected), "missing {expected:?}");
+        }
+    }
+
+    /// The expansion stands alone: every name in it is either generated here or
+    /// written in the declarations, so it cannot depend on the crate it lands in.
+    #[test]
+    fn names_no_crate_of_its_own() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap()
+        .to_string();
+
+        assert!(!generated.contains("xrpl_host_functions"), "{generated}");
+
+        // `Self::Variant` is the only path the expansion may build: anything else
+        // would reach out of the generated code. Doc comments spell paths without
+        // spaces (`Self::ALL`), so they do not match.
+        for (index, _) in generated.match_indices(" :: ") {
+            assert!(
+                generated[..index].ends_with("Self"),
+                "path out of the expansion at {index}: {generated}"
+            );
+        }
+    }
+
+    /// `spec` is an implementation detail of the two accessors, so it must not
+    /// become part of the ABI crate's public surface.
+    #[test]
+    fn keeps_the_table_row_private() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap()
+        .to_string();
+
+        assert!(!generated.contains("pub struct HostFnSpec"), "{generated}");
+        assert!(!generated.contains("pub const fn spec"), "{generated}");
+    }
+
+    #[test]
+    fn rejects_two_functions_that_share_a_wasm_name() {
+        let messages = messages(quote! {
+            #[gas = 60]
+            #[wasm_name = "trace"]
+            fn trace(&self, msg: &str) -> HostResult<()>;
+
+            #[gas = 70]
+            #[wasm_name = "trace"]
+            fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("already imported as `trace`"),
+            "{messages:?}"
+        );
+    }
+
+    /// Names that differ only in underscores collapse to one enum variant.
+    #[test]
+    fn rejects_two_functions_that_share_a_variant() {
+        let messages = messages(quote! {
+            #[gas = 60]
+            #[wasm_name = "a"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 70]
+            #[wasm_name = "b"]
+            fn get_ledger__sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("`GetLedgerSqn` variant"),
+            "{messages:?}"
+        );
+    }
+}

crates/xrpl-host-functions-macros/src/parsed_host_function.rs

@@ -0,0 +1,871 @@
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::{
+    Attribute, Expr, ExprLit, Ident, Lit, LitStr, PathArguments, ReceiverKind, ReturnType, Safety,
+    Signature, TraitItemFn, Type, TypePath,
+};
+
+use crate::errors;
+
+/// `#[gas = N]`: the base gas charged before the call runs.
+const GAS: &str = "gas";
+/// `#[wasm_name = "..."]`: the name the guest imports the function under.
+const WASM_NAME: &str = "wasm_name";
+/// `///` desugars to `#[doc = "..."]` before macro expansion.
+const DOC: &str = "doc";
+/// The alias every declaration returns its success type through.
+const HOST_RESULT: &str = "HostResult";
+
+/// One entry of a `host_functions!` block: its ABI metadata and its signature.
+pub(crate) struct ParsedHostFunction {
+    pub(crate) gas: u64,
+    /// Kept as the literal the user wrote, so diagnostics and the generated
+    /// string both carry that span.
+    pub(crate) wasm_name: LitStr,
+    /// Doc comments, in source order, to re-emit on the generated items.
+    pub(crate) docs: Vec<Attribute>,
+    /// The enum variant this declaration becomes, spanned at the function name.
+    pub(crate) variant: Ident,
+    pub(crate) signature: Signature,
+}
+
+impl ParsedHostFunction {
+    /// `#[doc …] fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;`
+    pub(crate) fn trait_method(&self) -> TokenStream {
+        let docs = &self.docs;
+        // The declaration is already a trait method: emitted verbatim, so what
+        // the block reads like is what the trait is.
+        let signature = &self.signature;
+
+        quote! {
+            #(#docs)*
+            #signature;
+        }
+    }
+
+    /// `#[doc …] GetLedgerSqn`
+    pub(crate) fn variant_declaration(&self) -> TokenStream {
+        let docs = &self.docs;
+        let variant = &self.variant;
+        quote! {
+            #(#docs)*
+            #variant
+        }
+    }
+
+    /// `Self::GetLedgerSqn => HostFnSpec { name: "ldgr_index", gas: 60u64 }`
+    pub(crate) fn spec_arm(&self) -> TokenStream {
+        let Self {
+            gas,
+            wasm_name,
+            variant,
+            ..
+        } = self;
+        quote! {
+            Self::#variant => HostFnSpec { name: #wasm_name, gas: #gas }
+        }
+    }
+
+    pub(crate) fn parse(function: TraitItemFn) -> syn::Result<Self> {
+        let mut gas = None;
+        let mut wasm_name = None;
+        let mut docs = Vec::new();
+        let mut errors = Vec::new();
+
+        // Tracked separately from `gas`/`wasm_name` so a malformed attribute is
+        // not also reported as a missing one.
+        let mut saw_gas = false;
+        let mut saw_wasm_name = false;
+
+        for attr in function.attrs {
+            if attr.path().is_ident(GAS) {
+                saw_gas = true;
+                if let Err(error) = int_value(&attr).and_then(|v| set_once(&mut gas, v, &attr)) {
+                    errors.push(error);
+                }
+            } else if attr.path().is_ident(WASM_NAME) {
+                saw_wasm_name = true;
+                if let Err(error) =
+                    string_value(&attr).and_then(|v| set_once(&mut wasm_name, v, &attr))
+                {
+                    errors.push(error);
+                }
+            } else if attr.path().is_ident(DOC) {
+                docs.push(attr);
+            } else {
+                errors.push(syn::Error::new_spanned(
+                    &attr,
+                    format!("unexpected attribute `{}`", path_name(&attr)),
+                ));
+            }
+        }
+
+        if !saw_gas {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                format!("missing `#[{GAS} = ...]` attribute"),
+            ));
+        }
+        if !saw_wasm_name {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                format!("missing `#[{WASM_NAME} = \"...\"]` attribute"),
+            ));
+        }
+        if let Some(body) = &function.default {
+            errors.push(syn::Error::new_spanned(
+                body,
+                "a host function is implemented by the host, so it must not have a body",
+            ));
+        }
+        if !function.sig.generics.params.is_empty() || function.sig.generics.where_clause.is_some()
+        {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                "a host function must not be generic: it maps to one wasm import signature",
+            ));
+        }
+        errors.extend(check_receiver(&function.sig).err());
+        errors.extend(check_return_type(&function.sig).err());
+        if let Some(name) = &wasm_name {
+            errors.extend(check_wasm_name(name).err());
+        }
+        reject_modifiers(&function.sig, &mut errors);
+
+        // A name whose PascalCase form is not a legal variant is reported here
+        // rather than emitted, which would either panic or fail downstream.
+        let variant = match variant_ident(&function.sig.ident) {
+            Ok(variant) => Some(variant),
+            Err(error) => {
+                errors.push(error);
+                None
+            }
+        };
+
+        if let Some(error) = errors::combine(errors) {
+            return Err(error);
+        }
+
+        let (Some(gas), Some(wasm_name), Some(variant)) = (gas, wasm_name, variant) else {
+            unreachable!("every absent field is reported above");
+        };
+
+        Ok(Self {
+            gas,
+            wasm_name,
+            docs,
+            variant,
+            signature: function.sig,
+        })
+    }
+}
+
+/// Every declaration carries a receiver, and it is always `&self`.
+///
+/// `&self` is the only receiver that can work: the VM reaches the host through a
+/// shared `&dyn HostFunctions` stored in the wasmi `Store`, and a host that needs
+/// to mutate does so behind interior mutability. The receiver is not part of the
+/// wasm ABI — the guest passes no `self` — so it is uniform across the block.
+fn check_receiver(signature: &Signature) -> syn::Result<()> {
+    let Some(receiver) = signature.receiver() else {
+        return Err(syn::Error::new_spanned(
+            &signature.ident,
+            format!(
+                "a host function must declare its receiver: `fn {}(&self, ...)`",
+                signature.ident
+            ),
+        ));
+    };
+
+    // `&self` and nothing else: not `&mut self`, not `self`/`mut self`, not a
+    // typed `self: Box<Self>`, and not a spelled-out lifetime.
+    if !matches!(receiver.kind, ReceiverKind::Reference(_, None, None)) {
+        return Err(syn::Error::new_spanned(
+            receiver,
+            "a host function's receiver must be exactly `&self`: the VM calls the host \
+             through a shared `&dyn HostFunctions`",
+        ));
+    }
+    Ok(())
+}
+
+/// Every declaration returns `HostResult<T>`, including the ones that yield
+/// nothing (`HostResult<()>`).
+///
+/// One shape for every function is what lets a single dispatch adapter lower them
+/// all: lift the arguments out of guest memory, call the host, then turn `Ok(T)`
+/// into the wire's non-negative `i32` and `Err(e)` into a negative code or a trap.
+/// A function returning a bare `T` would need its own arm.
+fn check_return_type(signature: &Signature) -> syn::Result<()> {
+    const SHAPE: &str = "a host function must return `HostResult<T>` — \
+                         `HostResult<()>` if it yields nothing";
+
+    let ReturnType::Type(_, returned) = &signature.output else {
+        return Err(syn::Error::new_spanned(&signature.ident, SHAPE));
+    };
+
+    let Type::Path(TypePath {
+        qself: None, path, ..
+    }) = &**returned
+    else {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    };
+    // The last segment only, so `HostResult<T>` may be written qualified.
+    let Some(last) = path.segments.last() else {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    };
+    if last.ident != HOST_RESULT {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    }
+
+    // `HostResult` without its success type is `HostResult` the alias, which names
+    // no type; rustc's own message for that is unhelpfully far from the cause.
+    let PathArguments::AngleBracketed(arguments) = &last.arguments else {
+        return Err(syn::Error::new_spanned(
+            returned,
+            format!("`{HOST_RESULT}` needs its success type: `{HOST_RESULT}<T>`"),
+        ));
+    };
+    if arguments.args.len() != 1 {
+        return Err(syn::Error::new_spanned(
+            arguments,
+            format!("`{HOST_RESULT}` takes exactly one type: `{HOST_RESULT}<T>`"),
+        ));
+    }
+    Ok(())
+}
+
+/// `const`, `async`, `unsafe`/`safe` and `extern "…"` have no meaning in the
+/// wasm ABI, and would otherwise pass silently into the generated trait.
+fn reject_modifiers(signature: &Signature, errors: &mut Vec<syn::Error>) {
+    const PLAIN: &str =
+        "a host function must be a plain `fn`: this modifier is not part of the wasm ABI";
+
+    if let Some(constness) = &signature.constness {
+        errors.push(syn::Error::new_spanned(constness, PLAIN));
+    }
+    if let Some(asyncness) = &signature.asyncness {
+        errors.push(syn::Error::new_spanned(asyncness, PLAIN));
+    }
+    match &signature.safety {
+        Safety::Default => {}
+        Safety::Safe(token) => errors.push(syn::Error::new_spanned(token, PLAIN)),
+        Safety::Unsafe(token) => errors.push(syn::Error::new_spanned(token, PLAIN)),
+    }
+    if let Some(abi) = &signature.abi {
+        errors.push(syn::Error::new_spanned(abi, PLAIN));
+    }
+}
+
+/// The wasm import name reaches the engine's import table verbatim, so it is
+/// held to what an import name can sanely be rather than to any string.
+fn check_wasm_name(name: &LitStr) -> syn::Result<()> {
+    let value = name.value();
+    if value.is_empty() {
+        return Err(syn::Error::new_spanned(
+            name,
+            "the wasm name must not be empty",
+        ));
+    }
+    if let Some(character) = value
+        .chars()
+        .find(|c| !c.is_ascii_alphanumeric() && *c != '_')
+    {
+        return Err(syn::Error::new_spanned(
+            name,
+            format!(
+                "a wasm name may only contain `A-Za-z0-9_`, but this one contains {character:?}"
+            ),
+        ));
+    }
+    Ok(())
+}
+
+/// The enum variant a declaration becomes: `get_ledger_sqn` -> `GetLedgerSqn`.
+///
+/// The result carries `ident`'s span, so anything the compiler says about the
+/// variant points at the declaration that produced it.
+fn variant_ident(ident: &Ident) -> syn::Result<Ident> {
+    // `to_string` spells raw identifiers `r#type`; the `r#` is not part of the name.
+    let name = ident.to_string();
+    let name = name.strip_prefix("r#").unwrap_or(&name);
+
+    let mut pascal = String::with_capacity(name.len());
+    let mut capitalize = true;
+    for character in name.chars() {
+        if character == '_' {
+            capitalize = true;
+        } else if capitalize {
+            pascal.extend(character.to_uppercase());
+            capitalize = false;
+        } else {
+            pascal.push(character);
+        }
+    }
+
+    // A name of nothing but underscores leaves `pascal` empty; the original is
+    // already a legal identifier, so keep it.
+    if pascal.is_empty() {
+        return Ok(ident.clone());
+    }
+
+    // `Ident::new` panics on a leading digit (`_2fa` -> `2fa`) and silently
+    // accepts keyword spellings (`self_` -> `Self`), which then fails to parse
+    // where the variant is emitted. Parsing rejects both, without panicking.
+    if let Err(error) = syn::parse_str::<Ident>(&pascal) {
+        return Err(syn::Error::new_spanned(
+            ident,
+            format!(
+                "this name becomes the enum variant `{pascal}`, which is not a valid \
+                 variant name ({error}); rename the host function"
+            ),
+        ));
+    }
+    Ok(format_ident!("{pascal}", span = ident.span()))
+}
+
+/// Records `value`, or reports that the attribute appeared more than once.
+fn set_once<T>(slot: &mut Option<T>, value: T, attr: &Attribute) -> syn::Result<()> {
+    if slot.replace(value).is_some() {
+        return Err(syn::Error::new_spanned(
+            attr,
+            format!("duplicate `{}` attribute", path_name(attr)),
+        ));
+    }
+    Ok(())
+}
+
+fn int_value(attr: &Attribute) -> syn::Result<u64> {
+    match &attr.meta.require_name_value()?.value {
+        Expr::Lit(ExprLit {
+            lit: Lit::Int(int), ..
+        }) => {
+            // `LitInt` keeps the sign in its digits, so `base10_parse::<u64>`
+            // would report a negative value as "invalid digit found in string".
+            if int.base10_digits().starts_with('-') {
+                return Err(syn::Error::new_spanned(
+                    int,
+                    format!("`{}` must not be negative", path_name(attr)),
+                ));
+            }
+            int.base10_parse()
+        }
+        other => Err(syn::Error::new_spanned(
+            other,
+            format!("`{}` expects an integer literal", path_name(attr)),
+        )),
+    }
+}
+
+fn string_value(attr: &Attribute) -> syn::Result<LitStr> {
+    match &attr.meta.require_name_value()?.value {
+        Expr::Lit(ExprLit {
+            lit: Lit::Str(string),
+            ..
+        }) => Ok(string.clone()),
+        other => Err(syn::Error::new_spanned(
+            other,
+            format!("`{}` expects a string literal", path_name(attr)),
+        )),
+    }
+}
+
+/// The attribute's path as written, for diagnostics: `gas`, or `foo::bar`.
+fn path_name(attr: &Attribute) -> String {
+    attr.path()
+        .segments
+        .iter()
+        .map(|segment| segment.ident.to_string())
+        .collect::<Vec<_>>()
+        .join("::")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use quote::ToTokens;
+    use syn::parse_quote;
+
+    /// The message of every diagnostic recorded by one failed `parse`.
+    ///
+    /// `expect_err` is unavailable here: it needs `T: Debug`, and syn only
+    /// implements `Debug` for its AST types under the `extra-traits` feature.
+    fn messages(function: TraitItemFn) -> Vec<String> {
+        let Err(error) = ParsedHostFunction::parse(function) else {
+            panic!("expected parsing to fail");
+        };
+        error.into_iter().map(|error| error.to_string()).collect()
+    }
+
+    fn doc_text(attr: &Attribute) -> String {
+        match &attr.meta.require_name_value().unwrap().value {
+            Expr::Lit(ExprLit {
+                lit: Lit::Str(text),
+                ..
+            }) => text.value(),
+            _ => panic!("doc attribute is not a string literal"),
+        }
+    }
+
+    #[test]
+    fn reads_gas_and_wasm_name() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert_eq!(parsed.gas, 60);
+        assert_eq!(parsed.wasm_name.value(), "ldgr_index");
+        assert_eq!(parsed.signature.ident.to_string(), "get_ledger_sqn");
+        assert_eq!(parsed.variant.to_string(), "GetLedgerSqn");
+        assert!(parsed.docs.is_empty());
+    }
+
+    #[test]
+    fn derives_variant_names_from_function_names() {
+        for (function, variant) in [
+            ("get_ledger_sqn", "GetLedgerSqn"),
+            ("sha512_half", "Sha512Half"),
+            ("trace", "Trace"),
+            ("get_current_ledger_obj_field", "GetCurrentLedgerObjField"),
+            ("r#type", "Type"),
+            ("trace2", "Trace2"),
+            // Pathological, but must not panic: no letters to capitalize.
+            ("__", "__"),
+        ] {
+            let ident = format_ident!("{function}");
+            assert_eq!(
+                variant_ident(&ident).map(|v| v.to_string()).ok(),
+                Some(variant.to_owned()),
+                "{function}"
+            );
+        }
+    }
+
+    /// `_2fa` would PascalCase to `2fa`; building that `Ident` panics, and a
+    /// panic in a proc macro is reported with no useful span at all.
+    #[test]
+    fn rejects_a_name_that_becomes_a_leading_digit() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "two_factor"]
+            fn _2fa(&self) -> HostResult<()>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("becomes the enum variant `2fa`"),
+            "{messages:?}"
+        );
+    }
+
+    /// `self_` PascalCases to `Self`, which `Ident::new` accepts and rustc then
+    /// rejects where the variant is emitted. `r#Self` is not a legal escape.
+    #[test]
+    fn rejects_a_name_that_becomes_a_keyword() {
+        for function in ["self_", "_self"] {
+            let ident = format_ident!("{function}");
+            let Err(error) = variant_ident(&ident) else {
+                panic!("expected `{function}` to be rejected");
+            };
+            assert!(
+                error.to_string().contains("variant `Self`"),
+                "{}",
+                error.to_string()
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_negative_gas() {
+        let messages = messages(parse_quote! {
+            #[gas = -5]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert_eq!(messages[0], "`gas` must not be negative");
+    }
+
+    #[test]
+    fn rejects_unusable_wasm_names() {
+        let empty = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = ""]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(empty.len(), 1, "{empty:?}");
+        assert_eq!(empty[0], "the wasm name must not be empty");
+
+        let spaced = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(spaced.len(), 1, "{spaced:?}");
+        assert!(spaced[0].contains("may only contain"), "{spaced:?}");
+    }
+
+    #[test]
+    fn rejects_signature_modifiers() {
+        for declaration in [
+            quote! { unsafe fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { async fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { const fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { extern "C" fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                #declaration
+            })
+            .unwrap();
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "{messages:?}");
+            assert!(messages[0].contains("must be a plain `fn`"), "{messages:?}");
+        }
+    }
+
+    #[test]
+    fn trait_method_keeps_the_declared_receiver_and_ends_in_a_semicolon() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            /// Hashes `data`.
+            #[gas = 2000]
+            #[wasm_name = "sha512_half"]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; 32]>;
+        })
+        .unwrap();
+
+        // `///` reaches the macro as `#[doc = r"..."]`: rustc's lexer spells doc
+        // comments as raw string literals.
+        let method = parsed.trait_method().to_string();
+        assert!(
+            method.starts_with("# [doc = r\" Hashes `data`.\"]"),
+            "{method}"
+        );
+        assert!(
+            method
+                .contains("fn sha512_half (& self , data : & [u8]) -> HostResult < [u8 ; 32] > ;"),
+            "{method}"
+        );
+    }
+
+    #[test]
+    fn spec_arm_carries_the_name_and_the_gas() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert_eq!(
+            parsed.spec_arm().to_string(),
+            "Self :: GetLedgerSqn => HostFnSpec { name : \"ldgr_index\" , gas : 60u64 }"
+        );
+    }
+
+    #[test]
+    fn keeps_doc_comments_in_source_order() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            /// First line.
+            ///
+            /// Third line.
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        let docs: Vec<_> = parsed.docs.iter().map(doc_text).collect();
+        assert_eq!(docs, vec![" First line.", "", " Third line."]);
+    }
+
+    #[test]
+    fn preserves_parameters_and_return_type() {
+        let traced = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 500]
+            #[wasm_name = "trace"]
+            fn trace(&self, msg: &str, data: &[u8], as_hex: bool) -> HostResult<()>;
+        })
+        .unwrap();
+        // The receiver is `inputs[0]`; the three wasm parameters follow it.
+        assert_eq!(traced.signature.inputs.len(), 4);
+        assert_eq!(
+            traced.signature.output.to_token_stream().to_string(),
+            "-> HostResult < () >"
+        );
+
+        let hashed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 2000]
+            #[wasm_name = "sha512_half"]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; HASH_LEN]>;
+        })
+        .unwrap();
+        assert_eq!(
+            hashed.signature.output.to_token_stream().to_string(),
+            "-> HostResult < [u8 ; HASH_LEN] >"
+        );
+    }
+
+    #[test]
+    fn reports_both_missing_attributes_at_once() {
+        let messages = messages(parse_quote! {
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2);
+        assert!(messages[0].contains("missing `#[gas"), "{messages:?}");
+        assert!(messages[1].contains("missing `#[wasm_name"), "{messages:?}");
+    }
+
+    #[test]
+    fn names_the_unexpected_attribute() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wsam_name = "typo"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        // The typo'd attribute, plus the `wasm_name` it failed to be.
+        assert_eq!(messages.len(), 2);
+        assert!(
+            messages.iter().any(|m| m.contains("`wsam_name`")),
+            "{messages:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_wrong_literal_types() {
+        let gas = messages(parse_quote! {
+            #[gas = "60"]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(gas.len(), 1, "{gas:?}");
+        assert!(
+            gas[0].contains("`gas` expects an integer literal"),
+            "{gas:?}"
+        );
+
+        let name = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = 7]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(name.len(), 1, "{name:?}");
+        assert!(
+            name[0].contains("`wasm_name` expects a string literal"),
+            "{name:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_gas_that_does_not_fit_in_u64() {
+        let messages = messages(parse_quote! {
+            #[gas = 99999999999999999999999]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(messages[0].contains("number too large"), "{messages:?}");
+    }
+
+    #[test]
+    fn rejects_attribute_shapes_other_than_name_value() {
+        let bare = messages(parse_quote! {
+            #[gas]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(bare.len(), 1, "{bare:?}");
+        assert!(bare[0].contains("gas = ..."), "{bare:?}");
+
+        let list = messages(parse_quote! {
+            #[gas(60)]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(list.len(), 1, "{list:?}");
+    }
+
+    #[test]
+    fn rejects_duplicate_attributes() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[gas = 70]
+            #[wasm_name = "ldgr_index"]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(messages[0].contains("duplicate `gas`"), "{messages:?}");
+        assert!(
+            messages[1].contains("duplicate `wasm_name`"),
+            "{messages:?}"
+        );
+    }
+
+    /// A malformed attribute must not also be reported as an absent one.
+    #[test]
+    fn does_not_report_a_malformed_attribute_as_missing() {
+        let messages = messages(parse_quote! {
+            #[gas = "60"]
+            #[wasm_name = 7]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(
+            !messages.iter().any(|m| m.contains("missing")),
+            "{messages:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_a_body() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]> { Ok([0; 4]) }
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(messages[0].contains("must not have a body"), "{messages:?}");
+    }
+
+    #[test]
+    fn rejects_generics() {
+        let parameter = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn<T>(&self) -> HostResult<T>;
+        });
+        assert_eq!(parameter.len(), 1, "{parameter:?}");
+        assert!(
+            parameter[0].contains("must not be generic"),
+            "{parameter:?}"
+        );
+
+        let clause = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]> where Self: Sized;
+        });
+        assert_eq!(clause.len(), 1, "{clause:?}");
+    }
+
+    #[test]
+    fn requires_a_receiver() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn() -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("must declare its receiver: `fn get_ledger_sqn(&self, ...)`"),
+            "{messages:?}"
+        );
+    }
+
+    /// Anything but `&self` would need a host the VM cannot hand out: it holds
+    /// one shared `&dyn HostFunctions` for the whole run.
+    #[test]
+    fn rejects_receivers_other_than_shared_self() {
+        for receiver in [
+            quote! { &mut self },
+            quote! { self },
+            quote! { mut self },
+            quote! { self: Box<Self> },
+            quote! { &'a self },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                fn get_ledger_sqn(#receiver) -> HostResult<[u8; 4]>;
+            })
+            .unwrap_or_else(|_| panic!("`{receiver}` should parse"));
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "`{receiver}`: {messages:?}");
+            assert!(
+                messages[0].contains("must be exactly `&self`"),
+                "`{receiver}`: {messages:?}"
+            );
+        }
+    }
+
+    /// A bare `T` return would need its own lowering arm, so the uniform shape is
+    /// required rather than inferred.
+    #[test]
+    fn rejects_returns_that_are_not_host_result() {
+        for output in [
+            quote! {},
+            quote! { -> () },
+            quote! { -> [u8; 4] },
+            quote! { -> i32 },
+            quote! { -> Result<[u8; 4], HostError> },
+            quote! { -> impl Iterator<Item = u8> },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                fn get_ledger_sqn(&self) #output;
+            })
+            .unwrap_or_else(|_| panic!("`{output}` should parse"));
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "`{output}`: {messages:?}");
+            assert!(
+                messages[0].contains("must return `HostResult<T>`"),
+                "`{output}`: {messages:?}"
+            );
+        }
+    }
+
+    /// `HostResult` may be written qualified, since the trait method keeps whatever
+    /// path resolves where the block is written.
+    #[test]
+    fn accepts_a_qualified_host_result() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> xrpl_host_functions::HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert!(
+            parsed
+                .trait_method()
+                .to_string()
+                .contains("xrpl_host_functions :: HostResult < [u8 ; 4] >"),
+            "{}",
+            parsed.trait_method()
+        );
+    }
+
+    /// `HostResult` with no success type names no type at all; rustc's own error
+    /// for that lands on the generated trait, far from the declaration.
+    #[test]
+    fn rejects_host_result_without_a_success_type() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("needs its success type"),
+            "{messages:?}"
+        );
+    }
+}

crates/xrpl-host-functions/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "xrpl-host-functions"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+xrpl-host-functions-macros.path = "../xrpl-host-functions-macros"

crates/xrpl-host-functions/src/lib.rs

@@ -0,0 +1,539 @@
+//! The wasm host ABI: the one place it is declared.
+//!
+//! `host_functions!` turns the declaration block at the bottom of this file into the
+//! [`HostFunctions`] trait a host implements and the [`HostFunctionSpec`] table a
+//! wasm engine registers from.
+//!
+//! The split: hand-written here is the vocabulary the declarations are written in —
+//! [`HostError`], [`TraceDataType`], [`HostResult`], [`HASH_LEN`] — and everything
+//! derived from the declarations is generated. The expansion names nothing this file
+//! does not, so the two sides meet only in the block below.
+//!
+//! So this file is lists — error codes, trace data types, functions. The `macro_rules!`
+//! that expand the first two into enums live in `macros.rs`.
+
+#![no_std]
+
+#[macro_use]
+mod macros;
+
+// Not re-exported: the ABI is declared once, here, and this is the only call site.
+use xrpl_host_functions_macros::host_functions;
+
+host_errors! {
+    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,
+    /// Internal fatal error.
+    /// User code will never see this error but keep it reserved to not rely on the value.
+    InternalFatal = -2147483648,
+}
+
+/// Convenience alias for the trait's fallible returns.
+pub type HostResult<T> = Result<T, HostError>;
+
+/// A `sha512Half` digest: the first 32 bytes of a SHA-512, as XRPL uses it.
+pub const HASH_LEN: usize = 32;
+
+trace_data_types! {
+    /// 8 little-endian bytes, rendered as a signed decimal.
+    Int64 = 1,
+    /// 8 little-endian bytes, rendered as an unsigned decimal.
+    Uint64 = 2,
+    /// A serialized XRPL float: 12 bytes, mantissa then exponent.
+    Xfloat = 3,
+    /// A 20-byte account ID, rendered as base58.
+    Account = 4,
+    /// A serialized `STAmount`.
+    Amount = 5,
+    /// Raw bytes, hex-encoded.
+    AsHex = 6,
+    /// Bytes rendered verbatim as text.
+    AsText = 7,
+}
+
+host_functions! {
+    /// The sequence number of the ledger being built, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "ldgr_index"]
+    fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The close time of the parent (last-closed) ledger, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_time"]
+    fn get_parent_ledger_time(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The hash of the parent (last-closed) ledger, as 32 bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_hash"]
+    fn get_parent_ledger_hash(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The base fee of the ledger being built, in drops, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "base_fee"]
+    fn get_base_fee(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// Whether an amendment is enabled. The input is either its 32-byte id or its
+    /// name; the answer is `1` if enabled and `0` if not. Unlike the getters, this
+    /// reads an input region and returns the flag directly rather than writing bytes.
+    #[gas = 100]
+    #[wasm_name = "amendment_enabled"]
+    fn is_amendment_enabled(&self, amendment: &[u8]) -> HostResult<i32>;
+
+    /// Load the ledger object with the given 32-byte id into a cache slot, so later
+    /// calls can read its fields. `cache_idx` selects the slot (1-based); `0` asks the
+    /// host to assign a free one. Returns the slot used, or a negative error.
+    #[gas = 5000]
+    #[wasm_name = "cache_le"]
+    fn cache_ledger_obj(&self, obj_id: &[u8], cache_idx: i32) -> HostResult<i32>;
+
+    /// The serialized bytes of one field of the transaction being executed, selected
+    /// by its `SField` code.
+    #[gas = 70]
+    #[wasm_name = "tx_field"]
+    fn get_tx_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of one field of the current (escrow) ledger object.
+    #[gas = 70]
+    #[wasm_name = "home_le_field"]
+    fn get_current_ledger_obj_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of one field of a previously cached ledger object,
+    /// selected by its cache slot and the field's `SField` code.
+    #[gas = 70]
+    #[wasm_name = "le_field"]
+    fn get_ledger_obj_field(&self, cache_idx: i32, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of the transaction, reached by a
+    /// `locator`: a path of little-endian `i32` steps (so its byte length is a
+    /// non-zero multiple of 4). Reads the locator region and writes the field bytes.
+    #[gas = 110]
+    #[wasm_name = "tx_inner"]
+    fn get_tx_nested_field(&self, locator: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of the current (escrow) ledger object,
+    /// reached by a `locator`, as with [`HostFunctions::get_tx_nested_field`].
+    #[gas = 110]
+    #[wasm_name = "home_le_inner"]
+    fn get_current_ledger_obj_nested_field(
+        &self,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of a previously cached ledger object,
+    /// selected by its cache slot and reached by a `locator`.
+    #[gas = 110]
+    #[wasm_name = "le_inner"]
+    fn get_ledger_obj_nested_field(
+        &self,
+        cache_idx: i32,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The number of elements in an array field of the transaction, selected by its
+    /// `SField` code. Answers the count directly, or a negative error (`NoArray` if
+    /// the field is not an array). Reads and writes no memory.
+    #[gas = 40]
+    #[wasm_name = "tx_arr_len"]
+    fn get_tx_array_len(&self, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in an array field of the current (escrow) ledger
+    /// object, as with [`HostFunctions::get_tx_array_len`].
+    #[gas = 40]
+    #[wasm_name = "home_le_arr_len"]
+    fn get_current_ledger_obj_array_len(&self, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in an array field of a previously cached ledger object,
+    /// selected by its cache slot and `SField` code.
+    #[gas = 40]
+    #[wasm_name = "le_arr_len"]
+    fn get_ledger_obj_array_len(&self, cache_idx: i32, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of the transaction, reached by a
+    /// `locator`. Reads the locator region and answers the count directly.
+    #[gas = 70]
+    #[wasm_name = "tx_inner_arr_len"]
+    fn get_tx_nested_array_len(&self, locator: &[u8]) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of the current (escrow) ledger
+    /// object, reached by a `locator`, as with [`HostFunctions::get_tx_nested_array_len`].
+    #[gas = 70]
+    #[wasm_name = "home_le_inner_arr_len"]
+    fn get_current_ledger_obj_nested_array_len(&self, locator: &[u8]) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of a previously cached ledger
+    /// object, selected by its cache slot and reached by a `locator`.
+    #[gas = 70]
+    #[wasm_name = "le_inner_arr_len"]
+    fn get_ledger_obj_nested_array_len(&self, cache_idx: i32, locator: &[u8]) -> HostResult<i32>;
+
+    /// Verify `signature` over `message` under `pubkey`. Reads the three regions and
+    /// answers `1` if the signature is valid, `0` if not, or a negative error.
+    ///
+    /// GAS DISCREPANCY: this 300 is the value the C-ABI fork registered
+    /// (`rippled-wasm-host-functions`, WasmVM.cpp), which this port follows. The
+    /// prior C++ integration in this tree charged 35000 for the same call — 100x
+    /// more, and closer to the real cost of signature verification. The value is
+    /// consensus-critical, so confirm which is intended before this ships.
+    #[gas = 300]
+    #[wasm_name = "check_sig"]
+    fn check_signature(
+        &self,
+        message: &[u8],
+        signature: &[u8],
+        pubkey: &[u8],
+    ) -> HostResult<i32>;
+
+    /// The 32-byte ledger key (keylet) of an account's `AccountRoot`, computed from a
+    /// 20-byte account id. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "accountroot_id"]
+    fn account_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an AMM, computed from its two assets. Each asset is a
+    /// byte slice whose length selects its kind (24 = MPT, 20 = XRP, 40 = issued
+    /// currency + issuer). Reads both asset regions and writes the keylet.
+    #[gas = 450]
+    #[wasm_name = "amm_id"]
+    fn amm_keylet(&self, asset1: &[u8], asset2: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Check`, computed from a 20-byte account id and its
+    /// sequence number. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "check_id"]
+    fn check_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Credential`, computed from the 20-byte subject and
+    /// issuer account ids and a credential-type byte string. Reads all three regions
+    /// and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "credential_id"]
+    fn credential_keylet(
+        &self,
+        subject: &[u8],
+        issuer: &[u8],
+        credential_type: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Delegate` object, computed from the 20-byte account
+    /// and the account it authorizes. Reads both account regions and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "delegate_id"]
+    fn delegate_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `DepositPreauth`, computed from the 20-byte account and
+    /// the account it authorizes to deposit. Reads both account regions and writes the
+    /// keylet.
+    #[gas = 350]
+    #[wasm_name = "deposit_preauth_id"]
+    fn deposit_preauth_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an account's `DID`, computed from its 20-byte account id.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "did_id"]
+    fn did_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Escrow`, computed from the 20-byte owner account and
+    /// its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "escrow_id"]
+    fn escrow_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `RippleState` (trust line), computed from two 20-byte
+    /// account ids and a 20-byte currency. Reads all three regions and writes the
+    /// keylet.
+    #[gas = 400]
+    #[wasm_name = "trustline_id"]
+    fn trust_line_keylet(
+        &self,
+        account1: &[u8],
+        account2: &[u8],
+        currency: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPTokenIssuance`, computed from the 20-byte issuer
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its
+    /// `i32` bit pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "mpt_issuance_id"]
+    fn mptoken_issuance_keylet(
+        &self,
+        issuer: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPToken`, computed from a 24-byte MPT issuance id and
+    /// the 20-byte holder account. Reads both regions and writes the keylet.
+    #[gas = 500]
+    #[wasm_name = "mptoken_id"]
+    fn mptoken_keylet(&self, mptid: &[u8], holder: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `NFTokenOffer`, computed from the 20-byte owner account
+    /// and its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "nft_offer_id"]
+    fn nftoken_offer_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Offer`, computed from the 20-byte owner account and
+    /// its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "offer_id"]
+    fn offer_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Oracle`, computed from the 20-byte owner account and
+    /// its document id. `doc_id` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "oracle_id"]
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PayChannel`, computed from the 20-byte source account,
+    /// the 20-byte destination account, and the channel's sequence number. `seq` is the
+    /// guest's `u32` carried as its `i32` bit pattern. Reads both account regions and
+    /// writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "paychan_id"]
+    fn paychannel_keylet(
+        &self,
+        account: &[u8],
+        destination: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PermissionedDomain`, computed from the 20-byte owner
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its `i32`
+    /// bit pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "permissioned_domain_id"]
+    fn permissioned_domain_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `SignerList`, computed from its 20-byte owner account.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "signers_id"]
+    fn signer_list_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Ticket`, computed from the 20-byte owner account and its
+    /// ticket sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "ticket_id"]
+    fn ticket_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Vault`, computed from the 20-byte owner account and its
+    /// sequence number. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "vault_id"]
+    fn vault_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The XRPL `sha512Half` of `data`: the first [`HASH_LEN`] bytes of its SHA-512.
+    #[gas = 2000]
+    #[wasm_name = "sha512_half"]
+    fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// Writes `msg` to the trace log, followed by `data` rendered as `data_type` says.
+    ///
+    /// The one declaration whose wasm function has **no result**: this node's own log
+    /// is its only effect, so a guest is told nothing. An `Err` from a host therefore
+    /// reaches it in no form, and only the host-fatal ones do anything at all.
+    ///
+    /// It is also the one declaration that is **not** the wasm parameter order.
+    /// `data_type` is the third wasm parameter, between the two regions, because that
+    /// is where xrpld's `trace_proto` and the guest stdlib put it; `register.rs` takes
+    /// the arguments in wasm order and calls this in declaration order.
+    #[gas = 30]
+    #[wasm_name = "trace"]
+    fn trace(&self, msg: &str, data: &[u8], data_type: TraceDataType) -> HostResult<()>;
+
+    /// Stores `data` as the current object's data field, replacing whatever was there,
+    /// and returns the number of bytes stored. Reads the data region; `DataFieldTooLarge`
+    /// if it exceeds the host's limit.
+    #[gas = 1000]
+    #[wasm_name = "set_data"]
+    fn update_data(&self, data: &[u8]) -> HostResult<i32>;
+
+    /// The URI of the `NFToken` with id `nft_id` (32 bytes) held by the 20-byte
+    /// `account`. Reads both regions and writes the URI bytes.
+    #[gas = 5000]
+    #[wasm_name = "nft_uri"]
+    fn get_nft(&self, account: &[u8], nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 20-byte issuer account encoded in the `NFToken` id `nft_id` (32 bytes).
+    /// Reads the id region and writes the issuer bytes.
+    #[gas = 70]
+    #[wasm_name = "nft_issuer"]
+    fn get_nft_issuer(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The taxon encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id region
+    /// and writes the taxon as its four little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "nft_taxon"]
+    fn get_nft_taxon(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The flags encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id region
+    /// and returns the flags as the call's scalar result.
+    #[gas = 60]
+    #[wasm_name = "nft_flags"]
+    fn get_nft_flags(&self, nft_id: &[u8]) -> HostResult<i32>;
+
+    /// The transfer fee encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id
+    /// region and returns the fee as the call's scalar result.
+    #[gas = 60]
+    #[wasm_name = "nft_xfer_fee"]
+    fn get_nft_transfer_fee(&self, nft_id: &[u8]) -> HostResult<i32>;
+
+    /// The sequence number encoded in the `NFToken` id `nft_id` (32 bytes). Reads the
+    /// id region and writes the sequence as its four little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "nft_serial"]
+    fn get_nft_sequence(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    // A "float" here is an XRPL `Number` in its serialized form: a byte blob the guest
+    // holds opaquely and hands back to these functions. Inputs and outputs that are
+    // floats are byte regions; `mode` is the rounding mode, a scalar the guest chooses.
+
+    /// A float built from the signed integer `x` under rounding `mode`. Writes the
+    /// float bytes; no input region.
+    #[gas = 100]
+    #[wasm_name = "float_from_int"]
+    fn float_from_int(&self, x: i64, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the unsigned integer in the 8-byte region `x` under rounding
+    /// `mode`. Reads the integer region and writes the float bytes.
+    #[gas = 130]
+    #[wasm_name = "float_from_uint"]
+    fn float_from_uint(&self, x: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the serialized `STAmount` in `amount` under rounding `mode`.
+    /// Reads the amount region and writes the float bytes.
+    #[gas = 150]
+    #[wasm_name = "float_from_stamount"]
+    fn float_from_stamount(&self, amount: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the serialized `STNumber` in `number` under rounding `mode`.
+    /// Reads the number region and writes the float bytes.
+    #[gas = 150]
+    #[wasm_name = "float_from_stnumber"]
+    fn float_from_stnumber(&self, number: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` rounded to a signed integer under rounding `mode`. Reads the float
+    /// region and writes the integer as its eight little-endian bytes.
+    #[gas = 130]
+    #[wasm_name = "float_to_int"]
+    fn float_to_int(&self, x: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` split into its mantissa and exponent. Reads the float region and
+    /// writes the mantissa (eight little-endian bytes) and the exponent (four little-
+    /// endian bytes) to two separate output regions.
+    #[gas = 130]
+    #[wasm_name = "float_to_mant_exp"]
+    fn float_to_mant_exp(
+        &self,
+        x: &[u8],
+        mantissa_out: &mut [u8],
+        exponent_out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// A float built from `mantissa` and `exponent` under rounding `mode`. Writes the
+    /// float bytes; no input region.
+    #[gas = 100]
+    #[wasm_name = "float_from_mant_exp"]
+    fn float_from_mant_exp(
+        &self,
+        mantissa: i64,
+        exponent: i32,
+        mode: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// Compares floats `x` and `y`, returning a negative, zero, or positive scalar as
+    /// `x` is less than, equal to, or greater than `y`. Reads both float regions.
+    #[gas = 80]
+    #[wasm_name = "float_cmp"]
+    fn float_compare(&self, x: &[u8], y: &[u8]) -> HostResult<i32>;
+
+    /// The float sum `x + y` under rounding `mode`. Reads both float regions and writes
+    /// the result bytes.
+    #[gas = 160]
+    #[wasm_name = "float_add"]
+    fn float_add(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float difference `x - y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 160]
+    #[wasm_name = "float_sub"]
+    fn float_subtract(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float product `x * y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 300]
+    #[wasm_name = "float_mult"]
+    fn float_multiply(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float quotient `x / y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 300]
+    #[wasm_name = "float_div"]
+    fn float_divide(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The `n`-th root of the float `x` under rounding `mode`. Reads the float region
+    /// and writes the result bytes.
+    #[gas = 5500]
+    #[wasm_name = "float_root"]
+    fn float_root(&self, x: &[u8], n: i32, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` raised to the power `n` under rounding `mode`. Reads the float
+    /// region and writes the result bytes.
+    #[gas = 5500]
+    #[wasm_name = "float_pow"]
+    fn float_power(&self, x: &[u8], n: i32, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+}

crates/xrpl-host-functions/src/macros.rs

@@ -0,0 +1,102 @@
+//! The `macro_rules!` behind the two hand-listed enums, [`crate::HostError`] and
+//! [`crate::TraceDataType`].
+//!
+//! Each takes one list of `Variant = code,` and expands the enum together with the
+//! `ALL`/`code`/`from_code` set that must not fall behind it. The lists themselves stay
+//! in `lib.rs`, beside the `host_functions!` block.
+
+/// Declares [`crate::HostError`] from one list: the variants, `HostError::ALL` and
+/// `HostError::from_code`'s table all expand from the codes given.
+///
+/// One list is what makes `ALL` complete. Rust cannot enumerate an enum's
+/// variants — an exhaustive `match` forces an arm per variant but gives nothing to
+/// iterate — so a hand-written `ALL` beside a hand-written enum could only be kept
+/// in step by review, and `ALL`'s whole purpose is to be the set a test can trust.
+/// A code added to the list gains its `ALL` entry and its `from_code` arm by
+/// construction. `HostFunctionSpec::ALL` is complete the same way, from the
+/// `host_functions!` block.
+macro_rules! host_errors {
+    ($($(#[$doc:meta])* $variant:ident = $code:literal,)+) => {
+        /// Error codes a host function may return.
+        ///
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        #[repr(i32)]
+        pub enum HostError {
+            $($(#[$doc])* $variant = $code,)+
+        }
+
+        impl HostError {
+            /// Every error a host function may return, in code order.
+            ///
+            /// The complete set, and complete by construction: a wasm engine's
+            /// split between the codes it hands the guest and the conditions it
+            /// traps on is a decision per variant, so the test that checks the
+            /// split iterates this and a code added to the ABI cannot slip past it.
+            pub const ALL: &'static [HostError] = &[$(HostError::$variant,)+];
+
+            /// The negative wire value a failed call returns. Every code but
+            /// `InternalFatal` is one a guest reads off that value.
+            #[inline]
+            pub const fn code(self) -> i32 {
+                self as i32
+            }
+
+            /// Reconstruct a `HostError` from its wire code.
+            ///
+            /// A code this ABI does not define is `InternalFatal`: an answer the
+            /// caller cannot act on is the call not having been served, and that is
+            /// the variant which says so. Positive values are not errors at all and go
+            /// the same way, since this is reached only once a negative return has
+            /// been read as a failure.
+            pub const fn from_code(code: i32) -> HostError {
+                match code {
+                    $($code => HostError::$variant,)+
+                    _ => HostError::InternalFatal,
+                }
+            }
+        }
+    };
+}
+
+/// Declares [`crate::TraceDataType`] from one list, so `TraceDataType::ALL`,
+/// `TraceDataType::code` and `TraceDataType::from_code` cannot fall behind the
+/// variants — the reason `host_errors!` above is written this way.
+macro_rules! trace_data_types {
+    ($($(#[$doc:meta])* $variant:ident = $code:literal,)+) => {
+        /// How [`HostFunctions::trace`] is to read its data buffer.
+        ///
+        /// The discriminants are wire values shared with the guest stdlib: append only,
+        /// never renumber. They start at 1, so a zeroed argument names no type rather
+        /// than the first one.
+        ///
+        /// This is the declaration a guest and a host both compile against. The host
+        /// side needs a second one — `cxx` cannot be a dependency here, since this
+        /// crate also links into the guest — so `xrpl-wasm-vm-ffi` declares a shared
+        /// enum for C++ and converts, exhaustively, from this.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        #[repr(i32)]
+        pub enum TraceDataType {
+            $($(#[$doc])* $variant = $code,)+
+        }
+
+        impl TraceDataType {
+            /// Every data type a guest may name, in code order.
+            pub const ALL: &'static [TraceDataType] = &[$(TraceDataType::$variant,)+];
+
+            /// The wire value a guest passes to name this type.
+            #[inline]
+            pub const fn code(self) -> i32 {
+                self as i32
+            }
+
+            /// The type `code` names, or `None`: the engine drops a call it cannot
+            /// read rather than guessing at a rendering the guest did not ask for.
+            pub const fn from_code(code: i32) -> Option<TraceDataType> {
+                match code {
+                    $($code => Some(TraceDataType::$variant),)+
+                    _ => None,
+                }
+            }
+        }
+    };
+}

crates/xrpl-host-functions/tests/expansion_hygiene.rs

@@ -0,0 +1,34 @@
+//! `host_functions!` must work outside the crate that declares the ABI: the only
+//! names its expansion needs are the ones the declarations themselves spell.
+
+use xrpl_host_functions::HostResult;
+use xrpl_host_functions_macros::host_functions;
+
+host_functions! {
+    /// Answers with the number it was given.
+    #[gas = 7]
+    #[wasm_name = "ping"]
+    fn ping(&self, number: i32) -> HostResult<i32>;
+}
+
+struct Host;
+
+impl HostFunctions for Host {
+    fn ping(&self, number: i32) -> HostResult<i32> {
+        Ok(number)
+    }
+}
+
+#[test]
+fn the_generated_table_stands_on_its_own() {
+    assert_eq!(HostFunctionSpec::ALL.len(), 1);
+    assert_eq!(HostFunctionSpec::Ping.wasm_name(), "ping");
+    assert_eq!(HostFunctionSpec::Ping.gas(), 7);
+}
+
+/// The generated trait is implementable from another crate, which is the point of
+/// declaring the ABI in a library at all.
+#[test]
+fn the_generated_trait_is_implementable_here() {
+    assert_eq!(Host.ping(3), Ok(3));
+}

crates/xrpl-host-functions/tests/host_errors.rs

@@ -0,0 +1,102 @@
+//! Exercises what `host_errors!` generates: the wire codes, the set
+//! [`HostError::ALL`] names, and the round trip between them.
+//!
+//! The codes are consensus input — they are what a guest reads off a failed host
+//! call — so they are pinned here as literals and derived everywhere else.
+
+use xrpl_host_functions::HostError;
+
+/// The whole set, written out in the order `ALL` gives it: the one place the wire
+/// codes appear as literals, and a deliberate change-detector, since a code that
+/// moves changes what every deployed guest is told.
+#[test]
+fn the_error_table_matches_the_declarations() {
+    let table: Vec<(HostError, i32)> = HostError::ALL
+        .iter()
+        .map(|&error| (error, error.code()))
+        .collect();
+
+    assert_eq!(
+        table,
+        [
+            (HostError::Unimplemented, -1),
+            (HostError::FieldNotFound, -2),
+            (HostError::BufferTooSmall, -3),
+            (HostError::NoArray, -4),
+            (HostError::NotLeafField, -5),
+            (HostError::LocatorMalformed, -6),
+            (HostError::SlotOutRange, -7),
+            (HostError::SlotsFull, -8),
+            (HostError::EmptySlot, -9),
+            (HostError::LedgerObjNotFound, -10),
+            (HostError::OutOfTransferLimit, -11),
+            (HostError::DataFieldTooLarge, -12),
+            (HostError::PointerOutOfBounds, -13),
+            (HostError::NoMemExported, -14),
+            (HostError::InvalidParams, -15),
+            (HostError::InvalidAccount, -16),
+            (HostError::InvalidField, -17),
+            (HostError::IndexOutOfBounds, -18),
+            (HostError::FloatInputMalformed, -19),
+            (HostError::FloatComputationError, -20),
+            (HostError::InternalFatal, i32::MIN),
+        ]
+    );
+}
+
+/// The guest-facing set is `-1 ..= -20` and nothing else: those entries are xrpld's
+/// `HostFunctionError`, and each is a code some contract may read.
+///
+/// `InternalFatal` is the one deliberate exception, exempted by name rather than by
+/// widening the range: a condition with no number a contract can act on needs no number
+/// in the range a contract reads, and holding it at `i32::MIN` is what keeps it from
+/// ever colliding with a code appended to xrpld's list.
+#[test]
+fn every_code_but_the_sentinel_is_in_the_shared_range() {
+    let shared: Vec<HostError> = HostError::ALL
+        .iter()
+        .copied()
+        .filter(|&error| error != HostError::InternalFatal)
+        .collect();
+
+    let outside: Vec<HostError> = shared
+        .iter()
+        .copied()
+        .filter(|error| !(-20..=-1).contains(&error.code()))
+        .collect();
+
+    assert!(outside.is_empty(), "outside -1..=-20: {outside:?}");
+    assert_eq!(shared.len(), 20);
+    assert_eq!(HostError::InternalFatal.code(), i32::MIN);
+    assert_eq!(HostError::ALL.len(), 21);
+}
+
+/// Every code a guest can be handed comes back as the error that produced it, so a
+/// caller reading a negative return value recovers the condition and not a
+/// neighbouring one. The table above pins the numbers; this adds only the round
+/// trip.
+#[test]
+fn every_wire_code_round_trips_back_to_its_error() {
+    for &error in HostError::ALL {
+        assert_eq!(HostError::from_code(error.code()), error, "{error:?}");
+    }
+}
+
+/// A code from outside the set is `InternalFatal`: a host answering something this ABI
+/// does not define has not served the call, whatever it meant by it, and success is not
+/// an error at all.
+///
+/// `-21` is the code xrpld would append next, so it is the one that decides whether a
+/// list this crate has not caught up with reaches a guest or stops the run. `i32::MIN +
+/// 1` is next to the sentinel and unassigned, which is what makes the sentinel a value
+/// rather than a range.
+#[test]
+fn a_code_outside_the_set_is_internal_fatal() {
+    for code in [-21, i32::MIN + 1, 0, 1, i32::MAX] {
+        assert_eq!(
+            HostError::from_code(code),
+            HostError::InternalFatal,
+            "{code}"
+        );
+    }
+}

crates/xrpl-wasm-testkit/Cargo.toml

@@ -1,13 +1,11 @@
 [package]
-name = "rs-hello_world"
+name = "xrpl-wasm-testkit"
 version = "0.1.0"
 edition.workspace = true
 
 [lib]
-crate-type = ["staticlib"]
+crate-type = ["staticlib", "rlib"]
 
 [dependencies]
 cxx.workspace = true
-
-[lints]
-workspace = true
+wat = "1"

crates/xrpl-wasm-testkit/src/lib.rs

@@ -0,0 +1,49 @@
+//! Assembles WebAssembly text for the C++ test suite. **Test-only.**
+//!
+//! A crate of its own rather than an entry on `xrpl-wasm-vm-ffi`, and the separation is the
+//! point. The engine pins `wasmi = { default-features = false }` precisely so a text
+//! assembler cannot reach the consensus path — wasmi's `wat` feature is on by default and
+//! makes `Module::new` accept text as readily as binary, which would make a transaction's
+//! validity a build flag (review finding A5). Putting `compile_wat` on the production bridge
+//! would link `wat` into xrpld even if nothing called it.
+//!
+//! Linked only into `xrpl_tests`, never into `libxrpl` or `xrpld`, so "no assembler in the
+//! shipped node" is a property of the link graph rather than a flag someone can flip.
+#![deny(rustdoc::broken_intra_doc_links)]
+
+#[cxx::bridge(namespace = "rs::wasm_testkit")]
+mod ffi {
+    extern "Rust" {
+        /// Assemble `wat` to a wasm module.
+        ///
+        /// Throws `rust::Error` on invalid input, which is what a test wants: a typo in a
+        /// fixture should fail the test that holds it, at the line that holds it.
+        fn compile_wat(wat: &str) -> Result<Vec<u8>>;
+    }
+}
+
+fn compile_wat(wat: &str) -> Result<Vec<u8>, wat::Error> {
+    wat::parse_str(wat)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::compile_wat;
+
+    #[test]
+    fn a_module_assembles_to_something_beginning_with_the_wasm_magic() {
+        let wasm = compile_wat("(module)").expect("assembles");
+
+        assert_eq!(&wasm[..4], b"\0asm");
+    }
+
+    #[test]
+    fn a_typo_is_an_error_rather_than_a_module() {
+        let error = compile_wat("(module (func (export").expect_err("must not assemble");
+
+        assert!(
+            !error.to_string().is_empty(),
+            "the error has to say something"
+        );
+    }
+}

crates/xrpl-wasm-vm-ffi/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "xrpl-wasm-vm-ffi"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+crate-type = ["staticlib", "rlib"]
+
+[dependencies]
+cxx.workspace = true
+xrpl-host-functions = { path = "../xrpl-host-functions" }
+xrpl-wasm-vm = { path = "../xrpl-wasm-vm" }

crates/xrpl-wasm-vm/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+wasmi = { version = "1.1.0", default-features = false, features = ["std"] }
+xrpl-host-functions = { path = "../xrpl-host-functions" }
+
+[dev-dependencies]
+wat = "1"

crates/xrpl-wasm-vm/src/abi.rs

@@ -0,0 +1,824 @@
+use crate::region::Region;
+use crate::vm::{MAX_FIELD_BYTES, VmState};
+use wasmi::{Caller, Memory};
+use xrpl_host_functions::{HostError, HostFunctionSpec, HostFunctions, HostResult};
+
+/// A condition that stops the run. It is a property of the run rather than an answer
+/// to a call, so it reaches no guest and carries no wire code — which is why it is
+/// not a [`HostError`]: no host can report one and no contract can read one.
+///
+/// The three are the outcomes a host call can end a run with, and
+/// `From<Fault> for RunError` in `vm.rs` is where each gets its name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Fault {
+    /// This call's charge would take the meter below zero. The guest exhausting the
+    /// meter with its own instructions reaches [`crate::vm::RunError::OutOfGas`] by
+    /// wasmi's `OutOfFuel` trap instead, never through here.
+    OutOfGas,
+    /// The call could not be served: either the host said so, or this engine's own
+    /// fuel meter did not answer.
+    Internal,
+    /// There is no linear memory to work in — the module exports none, or the call
+    /// came from a start section, which runs before there is an instance.
+    NoMemory,
+}
+
+/// How a host call fails: with a code the guest reads off the return value, or with a
+/// [`Fault`] that stops the run.
+///
+/// **The variant picks the channel.** [`to_wire`] reads it rather than asking a
+/// predicate, so the two cannot disagree, and a [`FatalHostError`] cannot be built
+/// around something a guest was supposed to see.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum CallError {
+    Code(HostError),
+    Fatal(Fault),
+}
+
+/// A host call's result inside the engine: [`HostResult`] plus the faults only the
+/// engine can raise.
+pub(crate) type CallResult<T> = Result<T, CallError>;
+
+/// Which channel a host's answer takes, decided once, here.
+///
+/// Three codes stop the run instead of reaching the contract that asked. Each says the
+/// call was not served at all — the host could not do it, it has not been wired, or
+/// there is nowhere to put the answer — and a contract has no business interpreting
+/// any of them, so it is told nothing and the run ends. Every other code is the
+/// contract's to read.
+impl From<HostError> for CallError {
+    fn from(error: HostError) -> CallError {
+        match error {
+            HostError::InternalFatal => CallError::Fatal(Fault::Internal),
+            HostError::Unimplemented => CallError::Fatal(Fault::Internal),
+            HostError::NoMemExported => CallError::Fatal(Fault::NoMemory),
+            code => CallError::Code(code),
+        }
+    }
+}
+
+/// The payload a trap carries so [`crate::vm::run`] can name the outcome without
+/// parsing a message. Holds a [`Fault`], so by construction no guest-visible code can
+/// leave through this channel.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct FatalHostError(pub(crate) Fault);
+
+impl wasmi::errors::HostError for FatalHostError {}
+
+impl core::fmt::Display for FatalHostError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "host call refused: {:?}", self.0)
+    }
+}
+
+/// Charge the call's gas, run its body, put the result on the wire. The one path
+/// every registered closure takes, so gas cannot be forgotten.
+pub(crate) fn charged(
+    caller: &mut Caller<'_, VmState<'_>>,
+    op: HostFunctionSpec,
+    body: impl FnOnce(&mut Caller<'_, VmState<'_>>) -> CallResult<i32>,
+) -> Result<i32, wasmi::Error> {
+    to_wire(charge(caller, op.gas()).and_then(|()| body(caller)))
+}
+
+/// [`charged`] for a call the guest gets no answer from: its wasm function has no
+/// result, so a soft error has nowhere to go and is dropped. The gas is charged first
+/// and charged whatever happens after, so the cost is all such a call leaves behind.
+///
+/// Only `trace` takes this path.
+pub(crate) fn charged_unreported(
+    caller: &mut Caller<'_, VmState<'_>>,
+    op: HostFunctionSpec,
+    body: impl FnOnce(&mut Caller<'_, VmState<'_>>) -> CallResult<()>,
+) -> Result<(), wasmi::Error> {
+    dropped(charge(caller, op.gas()).and_then(|()| body(caller)))
+}
+
+/// [`to_wire`] for a call with no result: there is no return value to encode a code
+/// in, so it is dropped. A [`Fault`] still stops the run — that is a property of the
+/// run, not an answer to the call.
+fn dropped(result: CallResult<()>) -> Result<(), wasmi::Error> {
+    match result {
+        Err(CallError::Fatal(fault)) => Err(wasmi::Error::host(FatalHostError(fault))),
+        _ => Ok(()),
+    }
+}
+
+fn to_wire(result: CallResult<i32>) -> Result<i32, wasmi::Error> {
+    match result {
+        Ok(value) => Ok(value),
+        Err(CallError::Code(error)) => Ok(error.code()),
+        Err(CallError::Fatal(fault)) => Err(wasmi::Error::host(FatalHostError(fault))),
+    }
+}
+
+/// Deduct `cost` fuel; [`Fault::OutOfGas`] if it would go negative.
+///
+/// A meter that will not answer is this crate's own defect, not the contract's, so it
+/// is [`Fault::Internal`] rather than a number a guest could act on.
+fn charge<T>(caller: &mut Caller<'_, T>, cost: u64) -> CallResult<()> {
+    let remaining = caller
+        .get_fuel()
+        .map_err(|_| CallError::Fatal(Fault::Internal))?;
+    match remaining.checked_sub(cost) {
+        Some(left) => caller
+            .set_fuel(left)
+            .map_err(|_| CallError::Fatal(Fault::Internal)),
+        None => {
+            let _ = caller.set_fuel(0);
+            Err(CallError::Fatal(Fault::OutOfGas))
+        }
+    }
+}
+
+fn charge_transfer(state: &VmState<'_>, n: usize) -> Result<(), HostError> {
+    let n = n as u64;
+    let remaining = state.transfer_budget.get();
+    match remaining.checked_sub(n) {
+        Some(left) => {
+            state.transfer_budget.set(left);
+            Ok(())
+        }
+        None => Err(HostError::OutOfTransferLimit),
+    }
+}
+
+fn memory(caller: &Caller<'_, VmState<'_>>) -> CallResult<Memory> {
+    caller
+        .data()
+        .memory
+        .ok_or(CallError::Fatal(Fault::NoMemory))
+}
+
+/// [`Region::read`] of the guest's memory, for a call that reads and writes nothing
+/// back (`trace`).
+pub(crate) fn read_borrowed<'a>(
+    caller: &'a Caller<'_, VmState<'_>>,
+    input: Region,
+) -> CallResult<&'a [u8]> {
+    let mem = memory(caller)?;
+    Ok(input.read(mem.data(caller))?)
+}
+
+/// Decode a guest `u32` argument — a keylet's sequence number or document id — from
+/// its four little-endian bytes, carried on to the host as its `i32` bit pattern.
+///
+/// The ABI transports these as a 4-byte region rather than a wasm scalar (the guest
+/// SDK passes `seq.to_le_bytes()`), so the region must be exactly four bytes;
+/// `InvalidParams` otherwise, matching the C-ABI wrapper's `getDataUInt32`.
+pub(crate) fn read_u32_arg(bytes: &[u8]) -> HostResult<i32> {
+    let arr: [u8; 4] = bytes.try_into().map_err(|_| HostError::InvalidParams)?;
+    Ok(i32::from_le_bytes(arr))
+}
+
+/// Service a call whose answer is bytes, written straight into the guest's output
+/// region.
+///
+/// **`fill` returns the value's true length, not what it wrote**: a host holding 64
+/// bytes and offered room for 4 writes nothing and answers `64`, which is how the
+/// guest learns the size to ask for. So `n` is bounded by neither the region nor the
+/// cap, and both checks below are reachable.
+pub(crate) fn write_into(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    fill: impl FnOnce(&dyn HostFunctions, &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let range = out.range()?;
+    let cap = range.len();
+    let mem = memory(caller)?;
+    let host: &dyn HostFunctions = caller.data().host;
+    // Bounds-checked over the guest's whole declared region, so a buffer running
+    // past memory is a wrong pointer rather than a truncated prefix being served…
+    let buf = mem
+        .data_mut(&mut *caller)
+        .get_mut(range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    // …of which only the field cap is writable, so no call can exceed it whatever
+    // the guest declared.
+    let buf = &mut buf[..cap.min(MAX_FIELD_BYTES)];
+
+    let n = fill(host, buf)?;
+
+    if n > MAX_FIELD_BYTES {
+        return Err(HostError::DataFieldTooLarge.into());
+    }
+    if n > cap {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    charge_transfer(caller.data(), n)?;
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "`n > MAX_FIELD_BYTES` returned above, and the cap is far inside i32"
+    )]
+    let n = n as i32;
+    Ok(n)
+}
+
+/// Service a call that reads guest memory and writes bytes back to it: the host
+/// fills the run's output buffer, which is copied to the guest once every rule has
+/// passed.
+///
+/// `call` gets the guest's whole memory, so it can borrow any number of input
+/// regions with [`Region::read`] — which a `&mut` view of that memory would forbid.
+/// That is why the answer goes through a buffer instead of straight into the guest
+/// as [`write_into`]'s does.
+///
+/// **The host is never told the guest's capacity**: it is offered the whole buffer
+/// and reports the value's true length, so the fit is decided here, with nothing yet
+/// in guest memory. A refused value therefore reaches it in no part.
+///
+/// The output is judged after the inputs, so a call with both bad reports the
+/// input's verdict. `NoMemExported` precedes both: there is no memory to validate a
+/// region against.
+pub(crate) fn write_buffered(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    // One borrow split in two: the guest's bytes for the inputs, the store data for
+    // the output buffer. Taking them together is what keeps the inputs borrowed
+    // rather than copied out.
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    let n = call(host, data, &mut state.out_buffer[..])?;
+
+    // `out` is checked here rather than before the call: the inputs are judged
+    // first, so a call with both malformed reports the input's verdict.
+    let range = out.range()?;
+    let cap = range.len();
+    if n > MAX_FIELD_BYTES {
+        return Err(HostError::DataFieldTooLarge.into());
+    }
+    let buf = data.get_mut(range).ok_or(HostError::PointerOutOfBounds)?;
+    if n > cap {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    charge_transfer(state, n)?;
+    buf[..n].copy_from_slice(&state.out_buffer[..n]);
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "`n > MAX_FIELD_BYTES` returned above, and the cap is far inside i32"
+    )]
+    let n = n as i32;
+    Ok(n)
+}
+
+/// The mantissa and exponent widths `float_to_mant_exp` writes: an `i64` and an `i32`.
+/// Fixed by the ABI, not the guest, so the split is a constant rather than a reported
+/// length.
+const MANTISSA_BYTES: usize = 8;
+const EXPONENT_BYTES: usize = 4;
+
+/// Service `float_to_mant_exp`, the one call that writes two output regions: the host
+/// fills the run's output buffer with the mantissa followed by the exponent, and each
+/// is copied to its own guest region once every rule has passed.
+///
+/// Like [`write_buffered`], the host reads its input from the guest's memory and writes
+/// to a scratch buffer, so the input stays borrowed rather than copied. The two output
+/// regions are judged after the input, and the mantissa's region before the exponent's,
+/// so the first fault reported is the leftmost.
+///
+/// The two widths are the ABI's rather than the guest's, so the length the host reports
+/// is checked against their sum for equality rather than as a bound, and ahead of the
+/// output regions: a wrong total means there is no answer to place, whatever the guest
+/// declared. That is a fatal error and not a status, since the guest asked for nothing
+/// wrong.
+pub(crate) fn write_mant_exp(
+    caller: &mut Caller<'_, VmState<'_>>,
+    mantissa_out: Region,
+    exponent_out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    // The scratch buffer is split at the fixed mantissa width: the host fills the first
+    // eight bytes with the mantissa and the next four with the exponent.
+    let (mant_buf, exp_buf) = state.out_buffer.split_at_mut(MANTISSA_BYTES);
+    let mant_buf = &mut mant_buf[..MANTISSA_BYTES];
+    let exp_buf = &mut exp_buf[..EXPONENT_BYTES];
+
+    let total = call(host, data, mant_buf, exp_buf)?;
+
+    // Both buffers are fixed-width and were offered whole, so the only length the host
+    // can correctly report is their sum. Anything else is the host contradicting the
+    // ABI: with the widths in doubt, part of what would be copied out is whatever the
+    // previous call left in the buffer, so none of it is copied.
+    if total != MANTISSA_BYTES + EXPONENT_BYTES {
+        return Err(HostError::InternalFatal.into());
+    }
+
+    // Copy the mantissa, then the exponent, each only if its whole value fits its
+    // region — a region too small is `BufferTooSmall`, with nothing written.
+    let mant_range = mantissa_out.range()?;
+    let mant_dst = data
+        .get_mut(mant_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    if mant_dst.len() < MANTISSA_BYTES {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    mant_dst[..MANTISSA_BYTES].copy_from_slice(&state.out_buffer[..MANTISSA_BYTES]);
+
+    let exp_range = exponent_out.range()?;
+    let exp_dst = data
+        .get_mut(exp_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    if exp_dst.len() < EXPONENT_BYTES {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    exp_dst[..EXPONENT_BYTES]
+        .copy_from_slice(&state.out_buffer[MANTISSA_BYTES..MANTISSA_BYTES + EXPONENT_BYTES]);
+
+    charge_transfer(state, MANTISSA_BYTES + EXPONENT_BYTES)?;
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "a total other than 12 returned above, and 12 is far inside i32"
+    )]
+    let total = total as i32;
+    Ok(total)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::vm::TRANSFER_LIMIT_BYTES;
+    use std::cell::Cell;
+    use wasmi::StoreLimitsBuilder;
+    use xrpl_host_functions::TraceDataType;
+
+    /// `charge_transfer` takes the store data, which has to hold a host.
+    struct UncalledHost;
+
+    impl HostFunctions for UncalledHost {
+        fn get_ledger_sqn(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_time(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_hash(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_base_fee(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn is_amendment_enabled(&self, _amendment: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn cache_ledger_obj(&self, _obj_id: &[u8], _cache_idx: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_field(
+            &self,
+            _cache_idx: i32,
+            _field: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_field(&self, _locator: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_field(
+            &self,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_field(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_array_len(&self, _cache_idx: i32, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_array_len(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_signature(
+            &self,
+            _message: &[u8],
+            _signature: &[u8],
+            _pubkey: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn account_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn amm_keylet(&self, _asset1: &[u8], _asset2: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn credential_keylet(
+            &self,
+            _subject: &[u8],
+            _issuer: &[u8],
+            _credential_type: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn delegate_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn deposit_preauth_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn did_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn escrow_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trust_line_keylet(
+            &self,
+            _account1: &[u8],
+            _account2: &[u8],
+            _currency: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_issuance_keylet(
+            &self,
+            _issuer: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_keylet(
+            &self,
+            _mptid: &[u8],
+            _holder: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn nftoken_offer_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn offer_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn oracle_keylet(
+            &self,
+            _account: &[u8],
+            _doc_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn paychannel_keylet(
+            &self,
+            _account: &[u8],
+            _destination: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn permissioned_domain_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn signer_list_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn ticket_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn vault_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn sha512_half(&self, _data: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trace(&self, _msg: &str, _data: &[u8], _data_type: TraceDataType) -> HostResult<()> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn update_data(&self, _data: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft(&self, _account: &[u8], _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_issuer(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_taxon(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_flags(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_transfer_fee(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_sequence(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_int(&self, _x: i64, _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_uint(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stamount(
+            &self,
+            _amount: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stnumber(
+            &self,
+            _number: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_int(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_mant_exp(
+            &self,
+            _x: &[u8],
+            _mantissa_out: &mut [u8],
+            _exponent_out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_mant_exp(
+            &self,
+            _mantissa: i64,
+            _exponent: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_compare(&self, _x: &[u8], _y: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_add(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_subtract(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_multiply(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_divide(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_root(&self, _x: &[u8], _n: i32, _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_power(
+            &self,
+            _x: &[u8],
+            _n: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+    }
+
+    fn state(budget: u64) -> VmState<'static> {
+        VmState {
+            host: &UncalledHost,
+            mem_limits: StoreLimitsBuilder::new().build(),
+            transfer_budget: Cell::new(budget),
+            memory: None,
+            out_buffer: [0u8; MAX_FIELD_BYTES],
+        }
+    }
+
+    /// `wasmi::Error` is not `PartialEq`, so a test expecting the guest-visible
+    /// channel says so by going through here.
+    fn wire(result: CallResult<i32>) -> i32 {
+        to_wire(result)
+            .unwrap_or_else(|trap| panic!("expected a guest-visible status, got a trap: {trap}"))
+    }
+
+    #[test]
+    fn a_success_becomes_the_value_and_an_error_becomes_its_code() {
+        assert_eq!(wire(Ok(0)), 0);
+        assert_eq!(wire(Ok(32)), 32);
+        assert_eq!(wire(Err(HostError::BufferTooSmall.into())), -3);
+    }
+
+    /// The codes a host may answer that a contract must not see, and the fault each
+    /// becomes. Written out rather than derived from `From<HostError>`, which is what
+    /// they are asserting.
+    const STOPS_THE_RUN: [(HostError, Fault); 3] = [
+        (HostError::InternalFatal, Fault::Internal),
+        (HostError::Unimplemented, Fault::Internal),
+        (HostError::NoMemExported, Fault::NoMemory),
+    ];
+
+    /// Every fault, so the two tests below are the whole set and not a sample.
+    /// `From<Fault> for RunError` is what forces a fault added later to be
+    /// considered; this is what forces it to be tested.
+    const ALL_FAULTS: [Fault; 3] = [Fault::OutOfGas, Fault::Internal, Fault::NoMemory];
+
+    #[test]
+    fn a_code_that_stops_the_run_converts_to_its_fault() {
+        for (error, fault) in STOPS_THE_RUN {
+            assert_eq!(CallError::from(error), CallError::Fatal(fault), "{error:?}");
+        }
+    }
+
+    /// Over `HostError::ALL`, so it is the whole ABI and not a sample: a code added
+    /// to the ABI arrives already asserted to reach the guest as itself, and stopping
+    /// the run on it is then a change someone has to come and make.
+    ///
+    /// `OutOfTransferLimit` is the row worth reading twice: the one budget a
+    /// contract can be expected to handle, so it is told no rather than killed.
+    #[test]
+    fn every_other_code_reaches_the_guest_as_itself() {
+        for &error in HostError::ALL {
+            if STOPS_THE_RUN.iter().any(|&(stops, _)| stops == error) {
+                continue;
+            }
+            assert_eq!(CallError::from(error), CallError::Code(error), "{error:?}");
+            assert_eq!(wire(Err(error.into())), error.code(), "{error:?}");
+        }
+    }
+
+    /// The trap carries the fault, so `run` can name the outcome without parsing a
+    /// message.
+    #[test]
+    fn a_fault_becomes_a_trap_carrying_it() {
+        for fault in ALL_FAULTS {
+            let trap = to_wire(Err(CallError::Fatal(fault)))
+                .expect_err("a fault must not reach the guest as a code");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    /// The result-less path splits the same two channels differently: a fault still
+    /// stops the run, and every code is dropped, since `trace` has no return value to
+    /// carry it. Over `HostError::ALL` for the reason above — a code added to the ABI
+    /// arrives asserted against both paths.
+    #[test]
+    fn a_call_with_no_result_drops_a_code_and_traps_on_a_fault() {
+        assert!(dropped(Ok(())).is_ok());
+
+        for &error in HostError::ALL {
+            if let CallError::Code(code) = CallError::from(error) {
+                assert!(
+                    dropped(Err(CallError::Code(code))).is_ok(),
+                    "{error:?} has no channel to the guest and must be dropped"
+                );
+            }
+        }
+
+        for fault in ALL_FAULTS {
+            let trap =
+                dropped(Err(CallError::Fatal(fault))).expect_err("a fault must stop the run");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    #[test]
+    fn a_transfer_spends_the_budget() {
+        let state = state(100);
+
+        assert_eq!(charge_transfer(&state, 30), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 70);
+        assert_eq!(charge_transfer(&state, 70), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The budget bounds the total, so the transfer that would overrun it is
+    /// refused whole rather than partially charged.
+    #[test]
+    fn a_transfer_past_the_budget_is_refused_and_charges_nothing() {
+        let state = state(100);
+
+        assert_eq!(
+            charge_transfer(&state, 101),
+            Err(HostError::OutOfTransferLimit)
+        );
+        assert_eq!(
+            state.transfer_budget.get(),
+            100,
+            "a refusal must not charge"
+        );
+        assert_eq!(charge_transfer(&state, 100), Ok(()));
+        assert_eq!(
+            charge_transfer(&state, 1),
+            Err(HostError::OutOfTransferLimit)
+        );
+    }
+
+    #[test]
+    fn transferring_nothing_costs_nothing() {
+        let state = state(0);
+
+        assert_eq!(charge_transfer(&state, 0), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The field cap holds one call to a small share of the run's budget, so the
+    /// budget bounds a run rather than a call. An inequality, not the two values:
+    /// those are pinned in `vm.rs`.
+    #[test]
+    fn no_single_value_can_exhaust_the_run_budget() {
+        assert!(
+            (MAX_FIELD_BYTES as u64) * 64 <= TRANSFER_LIMIT_BYTES,
+            "one {MAX_FIELD_BYTES}-byte value against a {TRANSFER_LIMIT_BYTES}-byte budget"
+        );
+    }
+}

crates/xrpl-wasm-vm/src/lib.rs

@@ -0,0 +1,28 @@
+//! The escrow wasm VM: compile a contract, meter it, and serve its host calls.
+//!
+//! Every guest access goes through `abi.rs` and reaches linear memory only by
+//! wasmi's bounds-checked slice operations; `forbid(unsafe_code)` makes that a
+//! property rather than a claim. The cast lints are on for the same reason — on a
+//! consensus path a truncating or sign-losing cast changes what a contract is
+//! charged or told, so each one is argued for at its site.
+#![forbid(unsafe_code)]
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(unreachable_pub)]
+#![deny(
+    clippy::cast_possible_truncation,
+    clippy::cast_possible_wrap,
+    clippy::cast_sign_loss,
+    clippy::cast_lossless
+)]
+
+mod abi;
+mod preflight;
+mod region;
+mod register;
+mod vm;
+
+pub use preflight::{CheckError, check};
+pub use vm::{
+    MAX_FIELD_BYTES, MAX_MEMORY_BYTES, MAX_MEMORY_PAGES, RunError, RunFailure, RunOutcome,
+    TRANSFER_LIMIT_BYTES, run,
+};

crates/xrpl-wasm-vm/src/preflight.rs

@@ -0,0 +1,351 @@
+//! Screening a contract before it reaches the ledger.
+//!
+//! [`check`] answers whether [`crate::run`] would refuse a module before the
+//! guest's first instruction — the three stages a caller maps to a malformed
+//! transaction rather than to a failed one. It needs **no host, no store and no
+//! gas**: everything it reads is a property of the compiled module. That is what
+//! makes it callable from a transaction's preflight, which has no ledger to serve
+//! host calls from.
+//!
+//! Two things it deliberately does not screen. A module exporting **no** linear
+//! memory passes: a contract that makes no host call needs none, and one that
+//! does is refused at the call and charged for what it burned. A start section
+//! passes: it is guest code, and executing it is the one thing a check must not do
+//! — a trap in one is charged to the contract like any other trap.
+//!
+//! One thing it screens that a run can only discover: an exported memory larger
+//! than the engine grants. See [`check_memory`] for what stays invisible.
+
+use std::fmt;
+use wasmi::{ExternType, FuncType, Module, ValType};
+use xrpl_host_functions::HostFunctionSpec;
+
+use crate::register::HOST_MODULE;
+use crate::vm::{MAX_MEMORY_PAGES, compile};
+
+/// Why a module cannot be run. One variant per stage, since the caller maps the
+/// stages separately.
+#[derive(Debug)]
+pub enum CheckError {
+    /// `wasm` is not a valid module under this engine's configuration.
+    Compile(String),
+    /// An import no engine of this ABI defines: another module namespace, a name
+    /// that is not a host function, or one imported as something other than a
+    /// function.
+    Import(String),
+    /// No export named `function_name` with signature `() -> i32`.
+    EntryPoint(String),
+    /// The module asks for more linear memory than the engine grants.
+    Memory(String),
+}
+
+impl fmt::Display for CheckError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            CheckError::Compile(detail) => write!(f, "compile: {detail}"),
+            CheckError::Import(detail) => write!(f, "import: {detail}"),
+            // The detail says which of the entry point's failures this is, since
+            // "no entry point" would be wrong for an export of the wrong type.
+            CheckError::EntryPoint(detail) => write!(f, "{detail}"),
+            CheckError::Memory(detail) => write!(f, "memory: {detail}"),
+        }
+    }
+}
+
+/// Screen `wasm`: it must compile, import only what the engine serves, export
+/// `function_name` as `() -> i32`, and ask for no more memory than it may have.
+///
+/// The stages are ordered by how much of the module each explains. An import fault
+/// is reported before a missing entry point because the imports are what the rest of
+/// the module is built on; memory comes last, being a resource request rather than a
+/// mistake about the ABI.
+pub fn check(wasm: &[u8], function_name: &str) -> Result<(), CheckError> {
+    let module = compile(wasm).map_err(CheckError::Compile)?;
+    check_imports(&module)?;
+    check_entry_point(&module, function_name)?;
+    check_memory(&module)
+}
+
+/// Every import must be one the linker defines. The first that is not ends the
+/// check, so a module with several faults reports the earliest.
+fn check_imports(module: &Module) -> Result<(), CheckError> {
+    for import in module.imports() {
+        check_import(import.module(), import.name(), import.ty()).map_err(CheckError::Import)?;
+    }
+    Ok(())
+}
+
+/// Whether the engine defines this one import.
+///
+/// The set of names is [`HostFunctionSpec::ALL`], which is also what
+/// [`crate::register::register_host_functions`] iterates — so a check and a run
+/// cannot disagree about which names exist, and adding a host function extends
+/// both at once. The one thing this does not compare is `ty`'s *signature*, which
+/// still parts a module from the engine at instantiation; the kind is compared
+/// because the engine defines these names as functions and as nothing else.
+///
+/// The rules are ordered, not merely alternatives: a guest importing `env::malloc`
+/// is told about the namespace rather than that `malloc` is not a host function,
+/// because the namespace is the one that explains every other import it has too.
+fn check_import(module: &str, name: &str, ty: &ExternType) -> Result<(), String> {
+    if module != HOST_MODULE {
+        return Err(format!("'{module}::{name}' is not from '{HOST_MODULE}'"));
+    }
+    if !HostFunctionSpec::ALL
+        .iter()
+        .any(|op| op.wasm_name() == name)
+    {
+        return Err(format!("no host function '{name}'"));
+    }
+    if !matches!(ty, ExternType::Func(_)) {
+        return Err(format!("'{HOST_MODULE}::{name}' is not a function"));
+    }
+    Ok(())
+}
+
+fn check_entry_point(module: &Module, name: &str) -> Result<(), CheckError> {
+    match module.get_export(name) {
+        Some(ExternType::Func(ty)) if is_entry_point(&ty) => Ok(()),
+        found => Err(CheckError::EntryPoint(entry_point_fault(found, name))),
+    }
+}
+
+/// The entry point's type: nothing in, one `i32` out — what [`crate::run`]'s
+/// `get_typed_func::<(), i32>` accepts.
+fn is_entry_point(ty: &FuncType) -> bool {
+    ty.params().is_empty() && matches!(ty.results(), [ValType::I32])
+}
+
+/// A module may not declare more linear memory than the engine grants.
+///
+/// Only what it *exports* is visible here. A memory a module keeps to itself is not
+/// in its exports, and the store's limiter is what refuses that one — at
+/// instantiation, where the run is charged nothing and the caller cannot tell it
+/// from any other resource failure. Screening the exported case covers every
+/// contract built against the guest SDK, since a contract needs an exported memory
+/// to make a host call at all.
+fn check_memory(module: &Module) -> Result<(), CheckError> {
+    for export in module.exports() {
+        if let ExternType::Memory(ty) = export.ty() {
+            check_initial_pages(ty.minimum()).map_err(CheckError::Memory)?;
+        }
+    }
+    Ok(())
+}
+
+/// Whether the engine will grant a memory of this declared initial size.
+///
+/// The *minimum* only: a declared maximum past the cap is legal and simply
+/// unreachable, which `vm_limits::a_declared_maximum_past_the_cap_is_allowed_but_
+/// unreachable` pins on the run side. Refusing it here would turn a runnable
+/// contract away.
+fn check_initial_pages(pages: u64) -> Result<(), String> {
+    if pages > u64::from(MAX_MEMORY_PAGES) {
+        return Err(format!(
+            "initial memory of {pages} pages is past the {MAX_MEMORY_PAGES}-page cap"
+        ));
+    }
+    Ok(())
+}
+
+/// How an entry-point lookup failed, in the words both stages use: a check and a
+/// run describe the same module the same way, and "no entry point" would send a
+/// contract author looking for a function they already have.
+pub(crate) fn entry_point_fault(found: Option<ExternType>, name: &str) -> String {
+    match found {
+        Some(ExternType::Func(_)) => {
+            format!("entry point '{name}' has the wrong signature, expected '() -> i32'")
+        }
+        Some(_) => format!("export '{name}' is not a function"),
+        None => format!("no entry point '{name}'"),
+    }
+}
+
+/// The rules, one by one, on inputs built directly rather than parsed out of a
+/// module. `tests/preflight.rs` runs real modules through [`check`]; what is here is
+/// what a module cannot state precisely — which rule fires, in which order, and in
+/// what words the caller logs it.
+///
+/// `wat` is a dev-dependency, so the one test here that does need a module writes it
+/// as text like every other test in the crate. What the library must not gain is a
+/// text *entry point* — `check` and `run` take binaries — and a `cfg(test)` caller
+/// cannot give it one.
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wasmi::{GlobalType, MemoryType, Mutability};
+
+    /// A host function as a guest declares it. Any function type will do: the
+    /// signature is not what [`check_import`] compares.
+    fn a_function() -> ExternType {
+        ExternType::Func(FuncType::new([ValType::I32], [ValType::I32]))
+    }
+
+    /// A name every one of these tests can use, taken from the ABI rather than
+    /// spelled, so it stays a real host function as the ABI changes.
+    fn a_host_function_name() -> &'static str {
+        HostFunctionSpec::ALL[0].wasm_name()
+    }
+
+    // -----------------------------------------------------------------------
+    // Imports
+    // -----------------------------------------------------------------------
+
+    /// Every name the ABI declares is served. Derived from `ALL` rather than
+    /// listed, so a host function added to the ABI is covered the day it lands.
+    #[test]
+    fn every_declared_host_function_is_served() {
+        for op in HostFunctionSpec::ALL {
+            assert_eq!(
+                check_import(HOST_MODULE, op.wasm_name(), &a_function()),
+                Ok(()),
+                "{}",
+                op.wasm_name()
+            );
+        }
+    }
+
+    #[test]
+    fn an_import_from_another_namespace_is_refused() {
+        for namespace in ["env", "host", "host_lib2", ""] {
+            let refusal = check_import(namespace, a_host_function_name(), &a_function())
+                .expect_err(namespace);
+            assert!(
+                refusal.contains("is not from 'host_lib'"),
+                "{namespace}: {refusal}"
+            );
+        }
+    }
+
+    #[test]
+    fn an_unknown_name_is_refused() {
+        let refusal =
+            check_import(HOST_MODULE, "no_such_function", &a_function()).expect_err("unknown name");
+        assert_eq!(refusal, "no host function 'no_such_function'");
+    }
+
+    /// The engine defines these names as functions and as nothing else, so a module
+    /// importing one as a global or a memory does not link either.
+    #[test]
+    fn a_host_function_imported_as_anything_else_is_refused() {
+        for ty in [
+            ExternType::Global(GlobalType::new(ValType::I32, Mutability::Const)),
+            ExternType::Memory(MemoryType::new(1, None)),
+        ] {
+            let name = a_host_function_name();
+            let refusal = check_import(HOST_MODULE, name, &ty).expect_err("not a function");
+            assert_eq!(refusal, format!("'host_lib::{name}' is not a function"));
+        }
+    }
+
+    /// The rules are ordered. An import that breaks two of them is reported by the
+    /// first, so the message a contract author reads is the one that explains the
+    /// rest of their imports too.
+    #[test]
+    fn the_namespace_is_reported_before_the_name() {
+        let refusal = check_import("env", "no_such_function", &a_function())
+            .expect_err("neither the namespace nor the name is served");
+
+        assert!(refusal.contains("is not from 'host_lib'"), "{refusal}");
+        assert!(
+            !refusal.contains("no host function"),
+            "the namespace explains it: {refusal}"
+        );
+    }
+
+    /// Both halves of the type are load-bearing, and neither is checked anywhere
+    /// a module cannot reach.
+    #[test]
+    fn the_entry_point_type_is_nothing_in_and_one_i32_out() {
+        assert!(is_entry_point(&FuncType::new([], [ValType::I32])));
+
+        for wrong in [
+            FuncType::new([], []),
+            FuncType::new([], [ValType::I64]),
+            FuncType::new([ValType::I32], [ValType::I32]),
+            FuncType::new([], [ValType::I32, ValType::I32]),
+        ] {
+            assert!(!is_entry_point(&wrong), "{wrong:?}");
+        }
+    }
+
+    /// Three faults, three descriptions. A run reports these too, with wasmi's own
+    /// error appended, so a swapped arm would mislead at both stages at once.
+    #[test]
+    fn each_entry_point_fault_is_described_as_itself() {
+        assert_eq!(
+            entry_point_fault(Some(a_function()), "finish"),
+            "entry point 'finish' has the wrong signature, expected '() -> i32'"
+        );
+        assert_eq!(
+            entry_point_fault(
+                Some(ExternType::Global(GlobalType::new(
+                    ValType::I32,
+                    Mutability::Const
+                ))),
+                "finish"
+            ),
+            "export 'finish' is not a function"
+        );
+        assert_eq!(
+            entry_point_fault(None, "finish"),
+            "no entry point 'finish'",
+            "an absent export must not be reported as a wrong signature"
+        );
+    }
+
+    /// The cap itself is granted; one page past it is not. The boundary is the whole
+    /// rule, and it is the same boundary the store's limiter applies at
+    /// instantiation.
+    #[test]
+    fn the_initial_memory_may_reach_the_cap_but_not_pass_it() {
+        assert_eq!(check_initial_pages(0), Ok(()));
+        assert_eq!(check_initial_pages(u64::from(MAX_MEMORY_PAGES)), Ok(()));
+
+        let past = u64::from(MAX_MEMORY_PAGES) + 1;
+        let refusal = check_initial_pages(past).expect_err("one page past the cap");
+        assert_eq!(
+            refusal,
+            format!("initial memory of {past} pages is past the {MAX_MEMORY_PAGES}-page cap")
+        );
+    }
+
+    /// The bridge logs this string and the C++ tests match on it, so the stage's
+    /// prefix is part of the interface rather than a debugging aid.
+    #[test]
+    fn a_refusal_names_its_stage() {
+        assert_eq!(
+            CheckError::Compile("bad magic".to_string()).to_string(),
+            "compile: bad magic"
+        );
+        assert_eq!(
+            CheckError::Memory("initial memory of 129 pages".to_string()).to_string(),
+            "memory: initial memory of 129 pages"
+        );
+        assert_eq!(
+            CheckError::Import("no host function 'x'".to_string()).to_string(),
+            "import: no host function 'x'"
+        );
+        // The entry point's detail already says which of its three faults it is,
+        // so a prefix would only repeat it.
+        assert_eq!(
+            CheckError::EntryPoint("no entry point 'finish'".to_string()).to_string(),
+            "no entry point 'finish'"
+        );
+    }
+
+    #[test]
+    fn the_stages_run_in_order() {
+        assert!(
+            matches!(check(b"not wasm", "finish"), Err(CheckError::Compile(_))),
+            "nothing is screened until the module compiles"
+        );
+
+        // A module that compiles and imports nothing, so it reaches the entry point.
+        let empty = wat::parse_str("(module)").expect("assembles");
+        assert!(
+            matches!(check(&empty, "finish"), Err(CheckError::EntryPoint(_))),
+            "a module that compiles and imports nothing reaches the entry point"
+        );
+    }
+}

crates/xrpl-wasm-vm/src/region.rs

@@ -0,0 +1,50 @@
+use crate::vm::MAX_FIELD_BYTES;
+use core::ops::Range;
+use xrpl_host_functions::{HostError, HostResult};
+
+/// A byte region as the guest declared it: the `(ptr, len)` pair off the wire, not
+/// yet checked.
+///
+/// Every byte parameter in this ABI is such a pair, so pairing them once at the wire
+/// boundary is what keeps the helpers in `abi.rs` from each taking two loose integers
+/// they could be handed in either order.
+///
+/// It lives in a module of its own so that the fields are out of reach and
+/// [`range`](Region::range) is the *only* way to indices — the check cannot be
+/// skipped, only deferred. Construction is infallible for that reason: a call whose
+/// output region is malformed is then refused in the order its own helper chooses,
+/// rather than at the moment the pair happened to be formed.
+#[derive(Copy, Clone)]
+pub(crate) struct Region {
+    ptr: i32,
+    len: i32,
+}
+
+impl Region {
+    pub(crate) fn new(ptr: i32, len: i32) -> Region {
+        Region { ptr, len }
+    }
+
+    /// `start..end` as indices. The conversion is the negativity check — it fails on
+    /// exactly the negative values — and the addition guards a 32-bit `usize`, where
+    /// two `i32`s can sum past the end.
+    pub(crate) fn range(self) -> HostResult<Range<usize>> {
+        let (Ok(start), Ok(len)) = (usize::try_from(self.ptr), usize::try_from(self.len)) else {
+            return Err(HostError::InvalidParams);
+        };
+        let end = start
+            .checked_add(len)
+            .ok_or(HostError::PointerOutOfBounds)?;
+        Ok(start..end)
+    }
+
+    /// The region's bytes, refused past the field cap. No copy: the slice aliases
+    /// `data`.
+    pub(crate) fn read(self, data: &[u8]) -> HostResult<&[u8]> {
+        let range = self.range()?;
+        if range.len() > MAX_FIELD_BYTES {
+            return Err(HostError::DataFieldTooLarge);
+        }
+        data.get(range).ok_or(HostError::PointerOutOfBounds)
+    }
+}