Let a contract emit transactions from its own pseudo-account

checkSign rejects every pseudo-account when BatchV1_1 is enabled, but
emitted transactions need BatchV1_1 to skip the signature check. So no
contract could emit anything. Allow a contract pseudo-account on inner
transactions, and make emitBuiltTxn and emitTxn reject a transaction
whose Account is not the running contract's account. Without that
check, a contract could emit an unsigned transaction from any account.

.clang-tidy

@@ -5,10 +5,7 @@ Checks: "-*,
   -bugprone-exception-escape,
   -bugprone-implicit-widening-of-multiplication-result,
   -bugprone-narrowing-conversions,
-  -bugprone-signed-bitwise,
-  -bugprone-std-exception-baseclass,
   -bugprone-throwing-static-initialization,
-  -bugprone-unhandled-code-paths,
 
   cppcoreguidelines-*,
   -cppcoreguidelines-avoid-c-arrays,
@@ -17,7 +14,6 @@ Checks: "-*,
   -cppcoreguidelines-avoid-magic-numbers,
   -cppcoreguidelines-avoid-non-const-global-variables,
   -cppcoreguidelines-c-copy-assignment-signature,
-  -cppcoreguidelines-explicit-constructor,
   -cppcoreguidelines-interfaces-global-init,
   -cppcoreguidelines-macro-usage,
   -cppcoreguidelines-missing-std-forward,
@@ -36,7 +32,6 @@ Checks: "-*,
   llvm-namespace-comment,
 
   misc-*,
-  -misc-explicit-constructor,
   -misc-multiple-inheritance,
   -misc-no-recursion,
   -misc-non-private-member-variables-in-classes,
@@ -50,8 +45,6 @@ Checks: "-*,
   -modernize-avoid-c-style-cast,
   -modernize-return-braced-init-list,
   -modernize-use-integer-sign-comparison,
-  -modernize-use-string-view,
-  -modernize-use-structured-binding,
   -modernize-use-trailing-return-type,
 
   performance-*,
@@ -60,7 +53,6 @@ Checks: "-*,
   -performance-noexcept-move-constructor,
   -performance-unnecessary-copy-initialization,
   -performance-unnecessary-value-param,
-  -performance-use-std-move,
 
   readability-*,
   -readability-avoid-const-params-in-decls,
@@ -73,11 +65,7 @@ Checks: "-*,
   -readability-named-parameter,
   -readability-qualified-auto,
   -readability-redundant-access-specifiers,
-  -readability-redundant-nested-if,
-  -readability-redundant-qualified-alias,
   -readability-static-accessed-through-instance,
-  -readability-trailing-comma,
-  -readability-trivial-switch,
   -readability-uppercase-literal-suffix
   "
 # ---
@@ -93,10 +81,6 @@ CheckOptions:
   bugprone-unsafe-functions.ReportMoreUnsafeFunctions: true
   bugprone-unused-return-value.CheckedReturnTypes: ::std::error_code;::std::error_condition;::std::errc
 
-  # New in clang-tidy 23; disabled until the code is updated
-  misc-const-correctness.AnalyzeAutoVariables: false
-  misc-const-correctness.AnalyzeLambdas: false
-  misc-const-correctness.AnalyzeParameters: false
   misc-include-cleaner.IgnoreHeaders: ".*/(detail|impl)/.*;.*fwd\\.h(pp)?;time.h;stdlib.h;sqlite3.h;netinet/in\\.h;sys/resource\\.h;sys/sysinfo\\.h;linux/sysinfo\\.h;__chrono/.*;bits/.*;_abort\\.h;boost/.*;openssl/obj_mac\\.h"
 
   readability-braces-around-statements.ShortStatementLines: 2
@@ -106,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
@@ -145,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

@@ -64,11 +64,11 @@ words:
   - blindings
   - bookdir
   - Bougalis
-  - bthomee
   - Britto
   - Btrfs
   - Buildx
   - canonicality
+  - cdylib
   - canonicalised
   - cctools
   - changespq
@@ -106,6 +106,7 @@ words:
   - deleteme
   - demultiplexer
   - deserializaton
+  - desugars
   - desync
   - desynced
   - determ
@@ -115,7 +116,7 @@ words:
   - dsymutil
   - dxrpl
   - elgamal
-  - enabled
+  - emittance
   - enablerepo
   - endmacro
   - envrc
@@ -132,6 +133,7 @@ words:
   - gcov
   - gcovr
   - ghead
+  - gmock
   - Gnutella
   - godexsoft
   - gpgcheck
@@ -141,8 +143,9 @@ words:
   - hwaddress
   - hwrap
   - ifndef
+  - impls
   - inequation
-  - Injectivity
+  - initialiser
   - insuf
   - insuff
   - invasively
@@ -252,10 +255,10 @@ words:
   - pyparsing
   - qalloc
   - qbsprofile
+  - qself
   - queuable
   - Raphson
   - rcflags
-  - reencrypted
   - replayer
   - repodata
   - repomd
@@ -309,7 +312,9 @@ words:
   - statsd
   - STATSDCOLLECTOR
   - stissue
+  - stjson
   - stnum
+  - stnumber
   - stobj
   - stobject
   - stpath
@@ -350,6 +355,7 @@ words:
   - unflatten
   - unfund
   - unimpair
+  - unmetered
   - unroutable
   - unscalable
   - unserviced
@@ -370,6 +376,8 @@ words:
   - vfalco
   - vinnie
   - wasmi
+  - wasmparser
+  - Werror
   - wextra
   - wptr
   - writeme
@@ -378,6 +386,7 @@ words:
   - xbridge
   - xchain
   - xcrun
+  - xfloat
   - ximinez
   - XMACRO
   - xored

.envrc

@@ -8,7 +8,3 @@ watch_file rust-toolchain.toml
 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

.gersemi/definitions.cmake

@@ -108,75 +108,3 @@ endfunction()
 
 function(patch_nix_binary target)
 endfunction()
-
-function(rpcspec_generate_instantiations)
-    set(options)
-    set(oneValueArgs OUT_VAR VALUE_TYPE VIEW_HEADER INCLUDE_DIR)
-    set(multiValueArgs HANDLERS)
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()
-
-function(corrosion_import_crate)
-    set(options
-        ALL_FEATURES
-        NO_DEFAULT_FEATURES
-        NO_STD
-        NO_LINKER_OVERRIDE
-        NO_USES_TERMINAL
-        LOCKED
-        FROZEN
-    )
-    set(oneValueArgs MANIFEST_PATH PROFILE IMPORTED_CRATES)
-    set(multiValueArgs
-        CRATE_TYPES
-        CRATES
-        FEATURES
-        FLAGS
-        OVERRIDE_CRATE_TYPE
-    )
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()
-
-function(corrosion_set_env_vars target_name env_var)
-endfunction()
-
-function(corrosion_add_cxxbridge cxx_target)
-    set(options)
-    set(oneValueArgs CRATE)
-    set(multiValueArgs FILES)
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()
-
-function(_unlink_libgcc_s crate)
-endfunction()
-
-function(add_xrpl_crate name)
-    set(options)
-    set(oneValueArgs CRATE)
-    set(multiValueArgs FILES)
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()

.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/CODEOWNERS

@@ -0,0 +1,2 @@
+# Allow anyone to review any change by default.
+*

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

@@ -15,9 +15,9 @@ inputs:
     required: false
     default: "false"
   log_verbosity:
-    description: 'The logging verbosity ("quiet", "verbose"), or empty to use the Conan defaults.'
+    description: "The logging verbosity."
     required: false
-    default: ""
+    default: "verbose"
   sanitizers:
     description: "The sanitizers to enable."
     required: false
@@ -35,16 +35,6 @@ runs:
         LOG_VERBOSITY: ${{ inputs.log_verbosity }}
         SANITIZERS: ${{ inputs.sanitizers }}
       run: |
-        # By default, leave the verbosity unset, so CMake configure output is
-        # shown, but compile commands and Boost's b2 debug output (~85k lines
-        # when "verbose") are not.
-        VERBOSITY_ARGS=()
-        if [[ -n "${LOG_VERBOSITY}" ]]; then
-            VERBOSITY_ARGS=(
-                --conf:all tools.build:verbosity="${LOG_VERBOSITY}"
-                --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}"
-            )
-        fi
         conan install \
             --profile:all ci \
             --build="${BUILD_OPTION}" \
@@ -52,13 +42,6 @@ runs:
             --options:host='&:xrpld=True' \
             --settings:all build_type="${BUILD_TYPE}" \
             --conf:all tools.build:jobs=${BUILD_NPROC} \
-            "${VERBOSITY_ARGS[@]}" \
-            --format=json \
-            . >"${RUNNER_TEMP}/conan-graph.json"
-
-    # Tools that run during the build may only load glibc from the Nix store,
-    # as their package ID survives a GCC runtime update.
-    - name: Check build-context packages for Nix store dependencies (Linux)
-      if: ${{ runner.os == 'Linux' }}
-      shell: bash
-      run: ./bin/nix/check-build-context-runtime.sh "${RUNNER_TEMP}/conan-graph.json"
+            --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
+            --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
+            .

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

@@ -15,25 +15,30 @@ outputs:
 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.
+    # A tag names its own version. Anything else takes it from BuildInfo.cpp and
+    # appends the commit hash as build metadata, joined with a plus sign because a
+    # Conan version cannot contain two hyphens.
     - 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 }}
+        SHA: ${{ github.sha }}
       run: |
         if [[ "${IS_TAG}" == "true" ]]; then
             version="${REF_NAME}"
         else
-            version="0.0.0-dev+${SHA:0:7}"
+            version="$(awk -F'"' '/versionString =/ { print $2 }' src/libxrpl/protocol/BuildInfo.cpp)"
+            if [[ -z "${version}" ]]; then
+                echo "Unable to read versionString from BuildInfo.cpp." >&2
+                exit 1
+            fi
+            version="${version}+${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
+      uses: XRPLF/actions/release-info@7cc0e4a8d9d0b838f92c48d312856b190341bbba

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

@@ -1,6 +1,9 @@
 benchmarks.libxrpl > xrpl.basics
 benchmarks.libxrpl > xrpl.config
 benchmarks.libxrpl > xrpl.nodestore
+benchmarks.libxrpl > xrpl.protocol
+benchmarks.libxrpl > xrpl.protocol_autogen
+benchmarks.libxrpl > xrpl.tx
 libxrpl.basics > xrpl.basics
 libxrpl.conditions > xrpl.basics
 libxrpl.conditions > xrpl.conditions
@@ -19,6 +22,7 @@ libxrpl.ledger > xrpl.json
 libxrpl.ledger > xrpl.ledger
 libxrpl.ledger > xrpl.nodestore
 libxrpl.ledger > xrpl.protocol
+libxrpl.ledger > xrpl.server
 libxrpl.ledger > xrpl.shamap
 libxrpl.net > xrpl.basics
 libxrpl.net > xrpl.net
@@ -82,6 +86,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 +117,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 +198,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
@@ -209,6 +210,7 @@ xrpl.core > xrpl.json
 xrpl.core > xrpl.protocol
 xrpl.json > xrpl.basics
 xrpl.ledger > xrpl.basics
+xrpl.ledger > xrpl.core
 xrpl.ledger > xrpl.json
 xrpl.ledger > xrpl.nodestore
 xrpl.ledger > xrpl.protocol
@@ -289,10 +291,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/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

@@ -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

@@ -12,17 +12,8 @@ _BASE_CMAKE_ARGS = [
     "-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"
-
 # Maps sanitizer names (as used in cmake) to short config-name suffixes.
 _SANITIZER_SUFFIX: dict[str, str] = {
     "address": "asan",
@@ -70,20 +61,10 @@ def get_cmake_args(build_type: str, extra_args: str) -> str:
 class PackageConfig:
     """The 'package' map of a config whose binaries are also packaged."""
 
-    type: str  # has to match what the image provides
+    type: str  # "deb" or "rpm"; 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)}."
-        )
 
 
 @dataclasses.dataclass
@@ -196,8 +177,6 @@ class PackagingEntry:
     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
 
 
 # ---------------------------------------------------------------------------
@@ -287,32 +266,12 @@ def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
                         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
-                        ),
                     )
                 )
 
     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.
 
@@ -381,10 +340,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-3d526d4",
+  "image_tag": "sha-060957e",
   "configs": {
     "ubuntu": [
       {
@@ -74,20 +74,7 @@
         "extra_cmake_args": "-Dvalidator_keys=ON",
         "package": {
           "type": "deb",
-          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-e6055dd"
-        }
-      },
-      {
-        "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-e6055dd",
-          "variant": "assert"
+          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-49cdc10"
         }
       }
     ],
@@ -101,7 +88,7 @@
         "extra_cmake_args": "-Dvalidator_keys=ON",
         "package": {
           "type": "rpm",
-          "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-e6055dd"
+          "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-49cdc10"
         }
       }
     ]

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

@@ -12,7 +12,8 @@ on:
       - "!nix/docker/README.md"
       - "!nix/devshell.nix"
       - "!nix/check-tools/**"
-      - "bin/nix/default-loader-path.sh"
+      - "bin/default-loader-path.sh"
+      - "bin/install-sanitizer-libs.sh"
   pull_request:
     paths:
       - ".github/workflows/build-nix-images.yml"
@@ -24,8 +25,8 @@ on:
       - "!nix/devshell.nix"
       - "!nix/check-tools/**"
       - "bin/check-tools.sh"
-      - "bin/nix/default-loader-path.sh"
-      - "bin/install/sanitizer-libs.sh"
+      - "bin/default-loader-path.sh"
+      - "bin/install-sanitizer-libs.sh"
   workflow_dispatch:
 
 concurrency:
@@ -57,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@034e87065fcd0100214cf0672923bd38d193cf78
     with:
       image_name: xrpld/nix-${{ matrix.distro.name }}
       dockerfile: nix/docker/Dockerfile

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

@@ -5,13 +5,14 @@ on:
     branches:
       - develop
     paths:
-      - "bin/install/packaging-tools.sh"
-      - "package/images/packaging/**"
+      - ".github/workflows/build-packaging-images.yml"
+      - "bin/install-packaging-tools.sh"
+      - "package/docker/**"
   pull_request:
     paths:
       - ".github/workflows/build-packaging-images.yml"
-      - "bin/install/packaging-tools.sh"
-      - "package/images/packaging/**"
+      - "bin/install-packaging-tools.sh"
+      - "package/docker/**"
   workflow_dispatch:
 
 concurrency:
@@ -40,9 +41,9 @@ jobs:
           # AlmaLinux rather than UBI, which does not ship rpm-sign.
           - name: rhel
             base_image: almalinux:10
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@696384b292577293292daed06af0306d1b83bd7d
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@034e87065fcd0100214cf0672923bd38d193cf78
     with:
       image_name: xrpld/packaging-${{ matrix.distro.name }}
-      dockerfile: package/images/packaging/Dockerfile
+      dockerfile: package/docker/Dockerfile
       base_image: ${{ matrix.distro.base_image }}
       push: ${{ github.event_name == 'push' }}

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

@@ -5,6 +5,7 @@ on:
     branches:
       - develop
     paths:
+      - ".github/workflows/build-pre-commit-image.yml"
       - "bin/pre-commit/Dockerfile"
       - "rust-toolchain.toml"
   pull_request:
@@ -29,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@034e87065fcd0100214cf0672923bd38d193cf78
     with:
       image_name: xrpld/pre-commit
       dockerfile: bin/pre-commit/Dockerfile

.github/workflows/cargo-audit.yml

@@ -34,7 +34,7 @@ permissions:
 jobs:
   audit:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     permissions:
       contents: read
       # Needed to open an issue on scheduled failures.

.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/on-pr.yml

@@ -85,7 +85,6 @@ jobs:
             .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,8 +92,9 @@ jobs:
             .github/workflows/reusable-upload-recipe.yml
             .clang-tidy
             .codecov.yml
+            bin/check-nix-store-refs.sh
             bin/check-tools.sh
-            bin/nix/**
+            bin/default-loader-path.sh
             cfg/**
             cmake/**
             conan/**
@@ -149,48 +149,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' }}
@@ -231,12 +189,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:
@@ -271,7 +223,6 @@ jobs:
       - check-autogen
       - check-levelization
       - check-rename
-      - check-release-commits
       - clang-tidy
       - build-test
       - rust

.github/workflows/on-tag.yml

@@ -1,12 +1,9 @@
 # When a versioned tag is pushed, this workflow:
 #
-#   - builds and tests the release binaries
 #   - uploads the libxrpl recipe to the Conan remote
+#   - builds and tests the release binaries
 #   - 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.
 name: Tag
 
 on:
@@ -25,7 +22,6 @@ 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 }}
@@ -54,7 +50,3 @@ jobs:
       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

@@ -23,7 +23,6 @@ on:
       - ".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,8 +30,9 @@ on:
       - ".github/workflows/reusable-upload-recipe.yml"
       - ".clang-tidy"
       - ".codecov.yml"
+      - "bin/check-nix-store-refs.sh"
       - "bin/check-tools.sh"
-      - "bin/nix/**"
+      - "bin/default-loader-path.sh"
       - "cfg/**"
       - "cmake/**"
       - "conan/**"
@@ -128,7 +128,3 @@ jobs:
       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

@@ -17,4 +17,4 @@ jobs:
     uses: XRPLF/actions/.github/workflows/pre-commit.yml@279ec358f4a1be4088be3e024b07916fa97c75b6
     with:
       runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-70b8fd3" }'
+      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-473fe44" }'

.github/workflows/publish-docs.yml

@@ -41,7 +41,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

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

@@ -31,12 +31,6 @@ on:
         type: string
         default: ""
 
-      unittest_args:
-        description: "Additional arguments to pass to rippled when running tests"
-        required: false
-        type: string
-        default: ""
-
       cmake_target:
         description: "The CMake target to build."
         required: true
@@ -192,6 +186,9 @@ jobs:
         with:
           build_nproc: ${{ steps.nproc.outputs.nproc }}
           build_type: ${{ inputs.build_type }}
+          # Set the verbosity to "quiet" for Windows to avoid an excessive
+          # amount of logs. For other OSes, the "verbose" logs are more useful.
+          log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
           sanitizers: ${{ inputs.sanitizers }}
 
       - name: Configure CMake
@@ -199,19 +196,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' }}' \
@@ -260,20 +244,19 @@ jobs:
       # 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/nix/check-nix-store-refs.sh "${BUILD_DIR}"
+        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/nix/check-nix-store-refs.sh "${CONAN_HOME}"
+        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/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
-          ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
-          ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpld_tests"
+          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
+          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
 
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
@@ -355,16 +338,13 @@ jobs:
       - 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 }}
         working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
         env:
           BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
-          UNITTEST_ARGS: ${{ inputs.unittest_args }}
         run: |
           set -o pipefail
           # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness
@@ -392,7 +372,10 @@ jobs:
       - name: Run Rust tests
         if: ${{ !inputs.build_only }}
         working-directory: crates
-        run: cargo nextest run --workspace --all-features --locked --no-tests=warn
+        # `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' || '' }}
 
       # Smoke-run every benchmark module with a single repetition to confirm the
       # benchmarks still build and execute. This is a correctness check, not a
@@ -459,7 +442,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

@@ -45,7 +45,6 @@ jobs:
       build_type: ${{ matrix.build_type }}
       ccache_enabled: ${{ inputs.ccache_enabled }}
       cmake_args: ${{ matrix.cmake_args }}
-      unittest_args: ${{ matrix.unittest_args }}
       cmake_target: ${{ matrix.cmake_target }}
       runs_on: ${{ toJSON(matrix.architecture.runner) }}
       image: ${{ matrix.image || '' }}

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

@@ -34,7 +34,7 @@ jobs:
     needs: [determine-files]
     if: ${{ needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.need_full_run == 'true' }}
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-3d526d4"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-060957e"
     permissions:
       contents: read
       issues: write
@@ -73,6 +73,7 @@ jobs:
         with:
           build_nproc: ${{ steps.nproc.outputs.nproc }}
           build_type: ${{ env.BUILD_TYPE }}
+          log_verbosity: verbose
 
       - name: Configure CMake
         working-directory: ${{ env.BUILD_DIR }}
@@ -85,7 +86,6 @@ jobs:
               -Dwerr=ON \
               -Dxrpld=ON \
               -Dverify_headers=ON \
-              -Drust=ON \
               ..
 
       - name: Build clang-tidy prerequisites

.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,17 +1,12 @@
 # Build, verify and publish Linux packages from the pre-built xrpld and
-# validator-keys artifacts, in these stages:
+# validator-keys artifacts, in three 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
+#   - 'test-install' installs what was built on a range of distros and runs 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.
 name: Package
@@ -28,7 +23,7 @@ on:
         description: "The base URL of the Nexus instance hosting the deb and rpm repositories."
         required: false
         type: string
-        default: https://packages-upload.xrplf.org
+        default: https://packages.xrplf.org
 
     secrets:
       remote_username:
@@ -38,19 +33,7 @@ on:
         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."
+        description: "Armoured PGP private key used to sign the RPMs. Required when publishing."
         required: false
 
 defaults:
@@ -66,8 +49,6 @@ jobs:
     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
@@ -126,7 +107,6 @@ jobs:
       - 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: |
@@ -134,7 +114,6 @@ jobs:
               --package-type "${PACKAGE_TYPE}" \
               --build-dir "${BUILD_DIR}" \
               --pkg-release "${PKG_RELEASE}" \
-              --variant "${PACKAGE_VARIANT}" \
               --channel "${CHANNEL}"
 
       # Before the upload, so the artifact, the tested package and the published
@@ -146,17 +125,14 @@ jobs:
         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-...'.
+      # that test-install downloads only what it installs.
       - 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/xrpld_*.deb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/xrpld-[0-9]*.rpm
           if-no-files-found: error
 
       - name: Upload debug symbol artifact
@@ -164,56 +140,133 @@ jobs:
         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
+            ${{ env.BUILD_DIR }}/debbuild/xrpld-dbgsym_*.deb
+            ${{ env.BUILD_DIR }}/debbuild/xrpld-dbgsym_*.ddeb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/xrpld-debuginfo-*.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"
-        ]
+  # Every distro family the packages target, oldest release first, so both ends
+  # of the dependency range they declare are exercised.
+  test-install:
+    needs: [package]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package_type: deb
+            image: debian:11
+          - package_type: deb
+            image: debian:12
+          - package_type: deb
+            image: debian:13
+          - package_type: deb
+            image: ubuntu:20.04
+          - package_type: deb
+            image: ubuntu:22.04
+          - package_type: deb
+            image: ubuntu:24.04
+          - package_type: deb
+            image: 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"
-        ]
+          - package_type: rpm
+            image: almalinux:9
+          - package_type: rpm
+            image: almalinux:10
+          - package_type: rpm
+            image: rockylinux/rockylinux:9
+          - package_type: rpm
+            image: rockylinux/rockylinux:10
+          - package_type: rpm
+            image: registry.access.redhat.com/ubi9/ubi
+          - package_type: rpm
+            image: registry.access.redhat.com/ubi10/ubi
+    name: "install ${{ matrix.package_type }} on ${{ matrix.image }}"
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    timeout-minutes: 5
+
+    steps:
+      # Both formats land in one directory; the step below picks its own by
+      # extension, so this stays 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_TYPE: ${{ matrix.package_type }}
+        run: |
+          package="$(find "${PACKAGE_DIR}" -type f -name "*.${PACKAGE_TYPE}" -print -quit)"
+          test -n "${package}" || {
+              echo "no .${PACKAGE_TYPE} 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: ${{ matrix.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: ${{ matrix.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
 
   publish:
-    needs: [generate-matrix, package, test-install-deb, test-install-rpm]
+    needs: [generate-matrix, package, test-install]
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-    name: "publish ${{ matrix.xrpld_artifact_name }}${{ !inputs.publish && ' (dry run)' || '' }}"
+    name: "publish ${{ matrix.xrpld_artifact_name }}"
     permissions:
       contents: read
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
@@ -254,95 +307,3 @@ jobs:
               --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

@@ -28,7 +28,7 @@ permissions:
 jobs:
   clippy:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -41,7 +41,7 @@ jobs:
 
   coverage:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -57,7 +57,7 @@ jobs:
 
       - 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,7 +70,7 @@ jobs:
 
   doc:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.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-3d526d4
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-060957e
     env:
       REMOTE_NAME: ${{ inputs.remote_name }}
       CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
@@ -68,17 +68,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.release_info.outputs.version }}
+          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.release_info.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 }}

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

@@ -108,11 +108,14 @@ jobs:
           build_nproc: ${{ steps.nproc.outputs.nproc }}
           build_type: ${{ matrix.build_type }}
           force_build: ${{ github.event_name == 'schedule' || github.event.inputs.force_source_build == 'true' }}
+          # Set the verbosity to "quiet" for Windows to avoid an excessive
+          # amount of logs. For other OSes, the "verbose" logs are more useful.
+          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/nix/check-nix-store-refs.sh "${CONAN_HOME}"
+        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') }}

.gitignore

@@ -92,9 +92,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: a9a8a861f30ed207ead7d5a3b7e8032283ba5da7 # frozen: v23.1.2
+    rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
     hooks:
       - id: clang-format
         args: [--style=file]
@@ -82,13 +77,12 @@ repos:
         files: ^crates/.*\.rs$
 
   - repo: https://github.com/BlankSpruce/gersemi-pre-commit
-    rev: 28010ddd6016e1a0f7bd232acb6536ef996ae897 # frozen: 0.29.2
+    rev: e98930bdc210d3387007f9252d8c1694ea7e410f # frozen: 0.27.7
     hooks:
       - id: gersemi
-        args: [-i, --warnings-as-errors]
 
   - 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]
@@ -96,26 +90,26 @@ repos:
   # 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: f12be1ebaa5351c1fc76472de98db2c3446c8253 # frozen: v0.16.10
+    rev: 7c55798a78262d14b2074abf623d8a992ebb70d4 # frozen: v0.16.2
     hooks:
       - id: ruff-check
         args: [--fix]
         files: ^package/.*\.py$
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 96ae3e5802f3fe2d551e703e18f0a367d1a81ac2 # frozen: 26.10.0
+    rev: 4160603246a6b365d4a2af661c6d71b0a0f50478 # frozen: 26.5.1
     hooks:
       - id: black
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 2834ec6639549dd6796205c8f011dedcd587288b # frozen: v2.4.0
+    rev: 41e691678310dfd3833f7ab4e180ddb014310356 # frozen: v2.3.0
     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]
@@ -134,7 +128,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

@@ -39,4 +39,4 @@ Paths below reflect the current layout; update this section if modularization mo
 - `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).
+- `crates/` — a Rust workspace holding the WebAssembly engine that runs Smart Escrow contracts, bridged into C++ via `cxxbridge`/the `cxx` crate; see [crates/README.md](./crates/README.md) for more details.

API-CHANGELOG.md

@@ -22,24 +22,6 @@ 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
-
-Version 3.5.0 is not yet released.
-
-### Additions in 3.5.0
-
-- `subscribe`, `unsubscribe`: Added an optional `mpt_issuances` request field, an array of MPT issuance IDs (hex strings). Subscribers receive the same `transaction` message as the `transactions` stream for each validated transaction whose metadata affects a subscribed issuance. 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))
-- `ledger_entry`: Add full support for checks, NFT offers, payment channels, and signer lists. ([#6319](https://github.com/XRPLF/rippled/pull/6319))
-
-### Bugfixes in 3.5.0
-
-- `channel_authorize`: The `channel_id` field now returns an `invalidParams` error if the value is not a string. [#7582](https://github.com/XRPLF/rippled/pull/7582)
-- `channel_verify`: The `channel_id` and `signature` fields now return an `invalidParams` error if the value is not a string. [#7582](https://github.com/XRPLF/rippled/pull/7582)
-
-### Bugfixes in 3.5.0
-
-- `feature`: The admin-only `vetoed` field now returns `invalidParams` unless its value is a boolean. [#7583](https://github.com/XRPLF/rippled/pull/7583)
-
 ## 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.
@@ -59,8 +41,6 @@ Version 3.4.0 is not yet released. These changes are available in the 3.4.0 beta
 - `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)).
-- `transaction_entry`: An object or an array in `tx_hash` now returns `malformedRequest`, like any other value that is not a hex hash, instead of an `internal` error.
 
 ## XRP Ledger server version 3.3.0
 

BUILD.md

@@ -1,6 +1,6 @@
-| :warning: **WARNING** :warning:                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md).<br><br>These instructions also assume a basic familiarity with Conan and CMake. If you are unfamiliar with Conan, you can read our [crash course](./docs/build/conan.md) or the official [Getting Started][conan-getting-started] walkthrough. |
+| :warning: **WARNING** :warning:                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, Rust, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md).<br><br>These instructions also assume a basic familiarity with Conan and CMake. If you are unfamiliar with Conan, you can read our [crash course](./docs/build/conan.md) or the official [Getting Started][conan-getting-started] walkthrough. |
 
 ## Minimum Requirements
 
@@ -41,19 +41,15 @@ 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
 
@@ -308,7 +304,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. |
@@ -323,23 +318,15 @@ builds may be faster for incremental builds, and can be helpful for detecting
 
 ### 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 build compiles the Rust workspace in `crates/` and generates the cxxbridge
+bindings the C++ side includes, so it needs a Rust toolchain (`cargo`, `rustc`)
+at the channel pinned in [`rust-toolchain.toml`](./rust-toolchain.toml). The
+[Nix development shell](./docs/build/nix.md) provides one; 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`):
+need only the Rust toolchain, independently of CMake (CI runs them with
+`cargo nextest`):
 
 ```bash
 cargo test --manifest-path crates/Cargo.toml --workspace

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
@@ -160,11 +160,8 @@ 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 +172,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
@@ -149,8 +145,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.
@@ -336,7 +332,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:
+Before running clang-tidy, you must generate the files it depends on (protobuf headers and 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
@@ -483,12 +479,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 +587,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 +608,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 +622,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 +1201,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

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

@@ -10,7 +10,7 @@
 # alone; the scripts in a Conan cache are all git hook samples and autotools
 # scratch, 36 false positives to 0 real.
 #
-# Usage: bin/nix/check-nix-store-refs.sh <path>
+# Usage: bin/check-nix-store-refs.sh <path>
 
 set -euo pipefail
 

bin/check-tools.sh

@@ -20,32 +20,19 @@
 # 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-<v>`, `g++-<v>`, ...) are probed under both names:
-# a suffixed name can break while the plain one still works
-# (see mkVersionedToolLinks in nix/packages.nix).
-# The suffix is the major version of the plain `clang` / `gcc` on PATH.
-#
-# Tools scoped to a single dev shell rather than to commonPackages are checked
-# only in that shell, keyed off XRPL_DEVSHELL.
+# 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).
 #
 # 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
 
-# major_version <compiler>
-# Major version of a compiler on PATH, or "unknown" when it isn't there.
-major_version() {
-    local version
-    version="$("$1" -dumpversion 2>/dev/null)" || version=""
-    version="${version%%.*}"
-    printf '%s' "${version:-unknown}"
-}
-
-llvm_version="$(major_version clang)"
+# Version suffixes of the Nix tool links, tracking nix/packages.nix.
+gcc_version=15
+llvm_version=22
 
 missing=()
 checked=0
@@ -121,7 +108,6 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     check ClangBuildAnalyzer
     check curl
     check file
-    check jq
     check less
     check make
     # net-tools netstat reports "net-tools X.Y"; macOS ships BSD netstat with no
@@ -177,20 +163,11 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     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:"
-    gcc_version="$(major_version gcc)"
     check gcc
     check "gcc-${gcc_version}"
     check g++

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/nix/check-build-context-runtime.sh

@@ -1,65 +0,0 @@
-#!/usr/bin/env bash
-# Fail if a binary of a build-context Conan package loads anything from the Nix
-# store other than glibc, or cannot resolve a library at all.
-#
-# Only binaries linked by the Nix toolchain are checked, i.e. those recording a
-# store path as their interpreter or RUNPATH. Prebuilt upstream binaries (such
-# as the ones the cmake package ships) use the system loader instead.
-#
-# Build-context packages provide the tools that run during the build (protoc,
-# grpc_cpp_plugin, ...). Their package ID does not change when a Nix toolchain
-# update moves the GCC runtime to a new store path, so a cached binary has to
-# get by with the pinned glibc alone. See docs/build/nix.md.
-#
-# Usage: bin/nix/check-build-context-runtime.sh <graph.json>
-#   <graph.json> is the output of `conan install --format=json`.
-
-set -euo pipefail
-
-if [ "$#" -ne 1 ]; then
-    echo "usage: $0 <graph.json>" >&2
-    exit 2
-fi
-
-if [ "$(uname -s)" != "Linux" ]; then
-    echo "$0: Linux only" >&2
-    exit 2
-fi
-
-folders="$(jq -r '.graph.nodes[] | select(.context == "build" and .package_folder) | .package_folder' "$1" | sort -u)"
-
-checked=0
-failed=0
-
-while IFS= read -r file; do
-    case "$(file -b "${file}")" in
-        ELF*) ;;
-        *) continue ;;
-    esac
-    [[ "$(readelf -ldW "${file}")" == */nix/store/* ]] || continue
-    checked=$((checked + 1))
-
-    # `ldd` lists the interpreter and every library as the loader resolves them.
-    if deps="$(ldd "${file}" 2>&1)"; then
-        bad="$(printf '%s\n' "${deps}" |
-            grep -E 'not found|/nix/store/' |
-            grep -vE '/nix/store/[^/]+-glibc-[^/]+/' || true)"
-    else
-        case "${deps}" in
-            *"not a dynamic executable"*) continue ;;
-        esac
-        bad="${deps}"
-    fi
-    if [ -n "${bad}" ]; then
-        failed=$((failed + 1))
-        echo "::error file=${file}::loads a library from the Nix store other than glibc"
-        echo "${file}"
-        echo "${bad}" | sed 's/^/    /'
-    fi
-done < <(
-    # shellcheck disable=SC2086 # one folder per line, no spaces in Conan paths
-    [ -z "${folders}" ] || find ${folders} -type f \( -perm -u+x -o -name '*.so*' \)
-)
-
-echo "Build-context packages: checked ${checked} binaries, ${failed} failed."
-[ "${failed}" -eq 0 ]

bin/pre-commit/Dockerfile

@@ -23,7 +23,7 @@ apt-get clean
 rm -rf /var/lib/apt/lists/*
 EOF
 
-ARG PRE_COMMIT_VERSION=4.6.2
+ARG PRE_COMMIT_VERSION=4.6.0
 RUN pip install --no-cache --break-system-packages \
     pre-commit==${PRE_COMMIT_VERSION}
 

bin/pre-commit/clang_tidy_check.py

@@ -26,6 +26,8 @@ import sys
 import tempfile
 from pathlib import Path
 
+CLANG_TIDY_VERSION = 22
+
 # Extensions run-clang-tidy can analyse: `.cpp` translation units and, thanks to
 # the `verify_headers` build option, `.h`/`.hpp` headers (each has its own
 # compile_commands.json entry). `.ipp` fragments have no entry and are skipped.
@@ -37,21 +39,8 @@ TIDY_EXTENSIONS = {".cpp", ".h", ".hpp"}
 FILEPATH_RE = re.compile(r"^(\s*(?:-\s+)?FilePath:\s*)'((?:[^']|'')*)'\s*$")
 
 
-def clang_tidy_major() -> str | None:
-    """Major version of the `clang-tidy` on PATH, which run-clang-tidy invokes."""
-    if not (clang_tidy := shutil.which("clang-tidy")):
-        return None
-    output = subprocess.run(
-        [clang_tidy, "--version"], capture_output=True, text=True
-    ).stdout
-    m = re.search(r"LLVM version (\d+)", output)
-    return m.group(1) if m else None
-
-
-def find_tool(name: str, version: str | None) -> str | None:
-    """Prefer `<name>-<version>`, so a host tool of another version can't win."""
-    candidates = ([f"{name}-{version}"] if version else []) + [name]
-    for candidate in candidates:
+def find_tool(name: str) -> str | None:
+    for candidate in (f"{name}-{CLANG_TIDY_VERSION}", name):
         if path := shutil.which(candidate):
             return path
     return None
@@ -114,9 +103,8 @@ def main():
     if not files:
         return 0
 
-    version = clang_tidy_major()
-    run_clang_tidy = find_tool("run-clang-tidy", version)
-    clang_apply_replacements = find_tool("clang-apply-replacements", version)
+    run_clang_tidy = find_tool("run-clang-tidy")
+    clang_apply_replacements = find_tool("clang-apply-replacements")
     missing = [
         name
         for name, path in (
@@ -126,10 +114,9 @@ def main():
         if not path
     ]
     if missing:
-        tried = f" (tried the '-{version}' suffix too)" if version else ""
         print(
             f"clang-tidy check failed: TIDY is enabled but {' and '.join(missing)} "
-            f"was not found in PATH{tried}.",
+            f"was not found in PATH (tried the '-{CLANG_TIDY_VERSION}' suffix too).",
             file=sys.stderr,
         )
         return 1

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

@@ -1360,6 +1360,39 @@
 #       Example:
 #           owner_reserve = 200000      # 0.2 XRP
 #
+#   gas_limit = <gas>
+#
+#       The gas limit is the maximum amount of gas that can be
+#       consumed by a single transaction. The gas limit is used to prevent
+#       transactions from consuming too many resources.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           gas_limit = 1000000      # 1 million gas
+#
+#   bytecode_size_limit = <bytes>
+#
+#       The bytecode size limit is the maximum size of a WASM extension in
+#       bytes. The size limit is used to prevent extensions from consuming
+#       too many resources.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           bytecode_size_limit = 100000      # 100 kb
+#
+#   gas_price = <micro-drops>
+#
+#       The gas price is the conversion between WASM gas and its price in drops.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           gas_price = 1000000      # 1 drop per gas
 #-------------------------------------------------------------------------------
 #
 # 9. Misc Settings

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/PatchNixBinary.cmake

@@ -17,7 +17,7 @@
    (runtime libraries resolved through the rpath) are skipped too.
    Everywhere else `patch_nix_binary` is a no-op.
 
-   The default loader is resolved by bin/nix/default-loader-path.sh.
+   The default loader is resolved by bin/default-loader-path.sh.
 #]===================================================================]
 
 include_guard(GLOBAL)
@@ -25,7 +25,7 @@ include_guard(GLOBAL)
 include(CompilationEnv)
 
 # Resolves the system default ELF loader path for the current architecture.
-set(_loader_path_script "${CMAKE_SOURCE_DIR}/bin/nix/default-loader-path.sh")
+set(_loader_path_script "${CMAKE_SOURCE_DIR}/bin/default-loader-path.sh")
 
 if(
     is_linux

cmake/XrplAddBenchmark.cmake

@@ -29,6 +29,14 @@ function(xrpl_add_benchmark name)
     # XrplCore.cmake. Each file compiles fine on its own.
     set_target_properties(${target} PROPERTIES UNITY_BUILD OFF)
 
+    # Land next to `xrpl_tests` in the build root rather than buried under
+    # `src/benchmarks/libxrpl/`. A benchmark is something a person runs by hand,
+    # repeatedly, and comparing two of them should not mean typing two long paths.
+    set_target_properties(
+        ${target}
+        PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+    )
+
     isolate_headers(
         ${target}
         "${CMAKE_SOURCE_DIR}/src"

cmake/XrplCore.cmake

@@ -81,7 +81,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 +111,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 +207,11 @@ target_link_libraries(
 )
 
 add_module(xrpl tx)
-target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)
+target_link_libraries(
+    xrpl.libxrpl.tx
+    PUBLIC xrpl.libxrpl.ledger xrpl_wasm_vm_ffi_cxxbridge
+)
+add_dependencies(xrpl.libxrpl.tx xrpl_crates)
 
 add_module(xrpl consensus)
 target_link_libraries(
@@ -275,6 +274,10 @@ if(xrpld)
     patch_nix_binary(xrpld)
     if(tests)
         target_compile_definitions(xrpld PUBLIC ENABLE_TESTS)
+        target_compile_definitions(
+            xrpld
+            PRIVATE UNIT_TEST_REFERENCE_FEE=${UNIT_TEST_REFERENCE_FEE}
+        )
     endif()
     target_include_directories(
         xrpld
@@ -288,14 +291,6 @@ if(xrpld)
     )
     target_sources(xrpld PRIVATE ${sources})
 
-    rpcspec_generate_instantiations(
-        OUT_VAR rpcspec_instantiations
-        VALUE_TYPE "::json::Value"
-        VIEW_HEADER "xrpld/rpc/detail/JsonObjectView.hpp"
-        HANDLERS book_changes ledger transaction_entry
-    )
-    target_sources(xrpld PRIVATE ${rpcspec_instantiations})
-
     if(tests)
         file(
             GLOB_RECURSE sources
@@ -305,14 +300,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
@@ -326,7 +314,6 @@ if(xrpld)
         # antithesis_instrumentation.h, which is not exported as INTERFACE
         target_include_directories(
             xrpld
-            SYSTEM
             PRIVATE ${CMAKE_SOURCE_DIR}/external/antithesis-sdk
         )
     endif()

cmake/XrplCov.cmake

@@ -48,7 +48,7 @@ setup_target_for_coverage_gcovr(
         "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

@@ -44,18 +44,12 @@ 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()
-
 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
+        --channel=UNRELEASED
     WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
     DEPENDS xrpld validator-keys
     COMMENT "Building Linux ${pkg_type} package"

cmake/XrplSanitizers.cmake

@@ -77,24 +77,19 @@ if(is_clang)
     message(STATUS "  Ignorelist: ${ignorelist_path}")
 endif()
 
-# Define the SANITIZERS macro for BuildInfo.cpp, plus one of XRPL_ASAN,
-# XRPL_TSAN and XRPL_UBSAN per active sanitizer, so that code can test for a
-# specific one with #ifdef instead of parsing the dot-joined SANITIZERS string.
+# Define SANITIZERS macro for BuildInfo.cpp
 set(sanitizers_list)
 if(SANITIZERS MATCHES "address")
     set(enable_asan ON)
     list(APPEND sanitizers_list "ASAN")
-    target_compile_definitions(common INTERFACE XRPL_ASAN)
 endif()
 if(SANITIZERS MATCHES "thread")
     set(enable_tsan ON)
     list(APPEND sanitizers_list "TSAN")
-    target_compile_definitions(common INTERFACE XRPL_TSAN)
 endif()
 if(SANITIZERS MATCHES "undefinedbehavior")
     set(enable_ubsan ON)
     list(APPEND sanitizers_list "UBSAN")
-    target_compile_definitions(common INTERFACE XRPL_UBSAN)
 endif()
 
 if(sanitizers_list)

cmake/XrplSettings.cmake

@@ -23,14 +23,15 @@ option(assert "Enables asserts, even in release builds" OFF)
 option(xrpld "Build xrpld" ON)
 
 option(tests "Build tests" ON)
+if(tests)
+    # This setting allows making a separate workflow to test fees other than default 10
+    if(NOT UNIT_TEST_REFERENCE_FEE)
+        set(UNIT_TEST_REFERENCE_FEE "10" CACHE STRING "")
+    endif()
+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

@@ -59,8 +59,9 @@ def create_transaction_parser():
 # the members that differ from these.
 SETTING_DEFAULTS = {
     "delegable": "Delegation::NotDelegable",
-    "amendment": "UInt256{}",
+    "amendment": "uint256{}",
     "privileges": "Privilege::NoPriv",
+    "emittance": "Emittance::Emitable",
 }
 
 

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.21#d536f87a2ae7d313452746cfa3ac4404%1790869005.122975",
         "sqlite3/3.53.0#324ada52333108388a9a6108bfa96734%1782392403.185447",
         "soci/4.0.3#e726491a03468795453f7c83fc924a96%1782392402.679521",
         "snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1782307151.633168",
@@ -20,8 +19,8 @@
         "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#aaa93ab6cda2f2baa6a84490582c8adf%1791284951.826256",
-        "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",
@@ -34,15 +33,11 @@
     "build_requires": [
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
         "strawberryperl/5.32.1.1#8d114504d172cfea8ea1662d09b6333e%1782395692.540639",
-        "re2/20251105#8579cfd0bda4daf0683f9e3898f964b4%1782392402.431897",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "openssl/3.6.3#f806de8933e3bf6f01016c6a888cee2e%1783945160.863288",
         "nasm/2.16.01#31e26f2ee3c4346ecd347911bd126904%1782395690.33162",
         "msys2/cci.latest#d22fe7b2808f5fd34d0a7923ace9c54f%1770657326.649",
         "m4/1.4.19#1727f439cf74e83826ec96d0b4904eee%1784541921.659",
-        "grpc/1.81.1#aaa93ab6cda2f2baa6a84490582c8adf%1791284951.826256",
         "cmake/4.3.3#840cf00ea09777e05c2050a50a82c722%1782392418.696091",
-        "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1782392402.681654",
         "b2/5.4.2#ffd6084a119587e70f11cd45d1a386e2%1782392402.624226",
         "automake/1.16.5#b91b7c384c3deaa9d535be02da14d04f%1755524470.56",
         "autoconf/2.71#51077f068e61700d65bb05541ea1e4b0%1731054366.86",
@@ -50,10 +45,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/global.conf

@@ -3,13 +3,5 @@
 core:non_interactive=True
 core.download:parallel={{ os.cpu_count() }}
 core.upload:parallel={{ os.cpu_count() }}
-# Fall back to Conan Center's source backups when a recipe's upstream URL is down
-# (e.g. the GNU FTP mirrors), see
-# https://github.com/conan-io/conan-center-index/issues/28147#issuecomment-3183544772
-# The backups are only tried once every upstream URL has used up its retries,
-# so keep the retries low.
-core.sources:download_urls=["origin", "https://c3i.jfrog.io/artifactory/conan-center-backup-sources"]
-tools.files.download:retry=1
+tools.files.download:retry=5
 tools.files.download:retry_wait=10
-# Fail fast on unreachable hosts (default connect timeout is 30s), keep the 60s read timeout.
-core.net.http:timeout=(5, 60)

conan/profiles/default

@@ -29,9 +29,9 @@ os.version={{ min_macos_version }}
 [conf]
 {# The Boost recipe builds with b2, which doesn't use Conan's toolchain files. #}
 {# Instead it hand-rolls the compiler for user-config.jam, #}
-{# and its fallback probes a version-suffixed binary (e.g. `g++-<major>`) before plain `g++`. #}
-{# Inside the Nix shell the wrapper only provides `g++`/`gcc` (no `-<major>` suffix), #}
-{# so on a host that also has a system `g++-<major>` the probe escapes Nix #}
+{# and its fallback probes a version-suffixed binary (e.g. `g++-15`) before plain `g++`. #}
+{# Inside the Nix shell the wrapper only provides `g++`/`gcc` (no `-15` suffix), #}
+{# so on a host that also has a system `g++-15` the probe escapes Nix #}
 {# and picks the system compiler, which is mismatched with the Nix libraries #}
 {# and breaks the build (e.g. Boost.Stacktrace link checks fail). #}
 {# Pinning the executables here short-circuits that probe so Boost (and the rest of the toolchain) #}
@@ -49,31 +49,8 @@ tools.build:compiler_executables={'c':'{{ cc_exe }}','cpp':'{{ cxx_exe }}'}
 user.package:cppstd_version=23
 tools.info.package_id:confs+=["user.package:cppstd_version"]
 
-{% if os == "Linux" and context == "build" %}
-{# Build-context executables (protoc, grpc_cpp_plugin, build tools) run during the build #}
-{# and would otherwise load libstdc++/libgcc from a Nix store path #}
-{# that might change with a Nix toolchain update. #}
-{# --as-needed drops the ones they link but don't use, #}
-{# such as libatomic for grpc_cpp_plugin on arm64. #}
-{% set static_runtime_flags = ["-static-libstdc++", "-static-libgcc", "-Wl,--as-needed"] %}
-tools.build:exelinkflags+={{ static_runtime_flags }}
-tools.info.package_id:confs+=["tools.build:exelinkflags"]
-{% endif %}
-
-{% if os == "Linux" and context == "build" %}
-{# b2 links itself with its own script, which ignores exelinkflags #}
-{# and only takes CXXFLAGS when use_cxx_env is set (see [buildenv] below). #}
-[options]
-b2/*:use_cxx_env=True
-{% endif %}
-
-[buildenv]
-{# gRPC emits thousands of compiler warnings that we cannot act on. #}
-{# CMake picks up CXXFLAGS, and unlike tools.build:cxxflags, #}
-{# this is not part of the package ID, so binaries stay shareable. #}
-grpc/*:CXXFLAGS=-w
-
 {% if os == "Macos" %}
+[buildenv]
 {# os.version adds -mmacosx-version-min to compiler command lines, #}
 {# but Boost.Context's b2 assembly (.S) rule ignores it, #}
 {# so those objects keep the host SDK version and still warn at link time. #}
@@ -81,7 +58,3 @@ grpc/*:CXXFLAGS=-w
 {# Scoped to boost/* since it is the only gap. #}
 boost/*:MACOSX_DEPLOYMENT_TARGET={{ min_macos_version }}
 {% endif %}
-
-{% if os == "Linux" and context == "build" %}
-b2/*:CXXFLAGS={{ static_runtime_flags | join(" ") }}
-{% endif %}

conan/profiles/sanitizers

@@ -5,9 +5,6 @@ include(default)
 
 {% if not sanitizers %}
 {# Sanitizers not configured; no additional settings needed #}
-{% elif context == "build" %}
-{# Build-context packages are tools we run, not code we test, #}
-{# so don't instrument them #}
 {% else %}
 
 {% if compiler == "msvc" %}

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"
@@ -40,7 +36,6 @@ class Xrpl(ConanFile):
         "nudb/2.0.9",
         "openssl/3.6.3",
         "soci/4.0.3",
-        "xrpl-rpc-spec/0.1.21",
         "zlib/1.3.2",
     ]
 
@@ -49,8 +44,7 @@ class Xrpl(ConanFile):
     ]
 
     tool_requires = [
-        "grpc/<host_version>",
-        "protobuf/<host_version>",
+        "protobuf/6.33.5",
     ]
 
     default_options = {
@@ -120,16 +114,17 @@ class Xrpl(ConanFile):
         "soci/*:shared": False,
         "soci/*:with_sqlite3": True,
         "soci/*:with_boost": True,
-        "xrpl-rpc-spec/*:server": "xrpld",
         "xxhash/*:shared": False,
     }
 
-    # default_options only reach the host context;
-    # give tool_requires (and their dependencies) the same dependency options.
-    default_build_options = {k: v for k, v in default_options.items() if "/" in k}
-
     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":
@@ -154,12 +149,15 @@ class Xrpl(ConanFile):
         self.requires("xxhash/0.8.3", transitive_headers=True)
 
     exports_sources = (
-        "bin/nix/default-loader-path.sh",
         "CMakeLists.txt",
         "cfg/*",
         "cmake/*",
+        "crates/*",
+        "crates/.cargo/*",
+        "!crates/target/*",
         "external/*",
         "include/*",
+        "rust-toolchain.toml",
         "src/*",
     )
 
@@ -172,17 +170,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/CMakeLists.txt

@@ -80,12 +80,13 @@ function(add_xrpl_crate name)
     # `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>")
+        corrosion_set_env_vars(
+            ${ARG_CRATE}
+            "$<$<CONFIG:Debug>:CXXFLAGS=-MTd>"
+        )
     endif()
-    corrosion_add_cxxbridge(
-        ${name}_cxxbridge
-        CRATE ${ARG_CRATE}
-        FILES ${ARG_FILES}
+    corrosion_add_cxxbridge(${name}_cxxbridge CRATE ${ARG_CRATE} FILES
+                            ${ARG_FILES}
     )
     # Generated cxxbridge headers don't exist at configure time; CMake 3.28+
     # validates INTERFACE_SOURCES on consuming targets. Clear it to skip the
@@ -100,4 +101,11 @@ function(add_xrpl_crate name)
     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)
+
+add_xrpl_crate(xrpl_wasm_testkit CRATE xrpl_wasm_testkit FILES lib.rs)
+
+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.199"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "13f6de320895f42e6e081abb5c7983bedcf0b6d0ff9323de0d33f620c8ac1199"
+checksum = "824894a4a85dca76d4c95c2b9098c036f5a29f627b30c12780774f6654e60974"
 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.199"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fde53ca86b9704a943fef0f1e1d836239a6aedca5de3c65fa9f97ec0bd46d39"
+checksum = "f1ae0b651ea5b0000b19513aef5a03f194d7e3486f2d9258b658da8677fe9036"
 dependencies = [
  "cc",
  "codespan-reporting",
@@ -87,9 +99,9 @@ dependencies = [
 
 [[package]]
 name = "cxxbridge-cmd"
-version = "1.0.202"
+version = "1.0.199"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bae89236c811fd4d08ed3441759ac4ac98d752cbfd3de341315ba16ad20ec3"
+checksum = "fb05f91d3fb8435d9bab6ac5ce6ac1868be774325fb7fb2a91be39393b21388e"
 dependencies = [
  "clap",
  "codespan-reporting",
@@ -101,15 +113,15 @@ dependencies = [
 
 [[package]]
 name = "cxxbridge-flags"
-version = "1.0.202"
+version = "1.0.199"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49045042e5fced01b80742aba5508de82aa4f13677ed3fa2b4cda709c40c5918"
+checksum = "bf293202e0e3e98495785745389e8d0755b217e66f19194a5c695c25e03282ef"
 
 [[package]]
 name = "cxxbridge-macro"
-version = "1.0.202"
+version = "1.0.199"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b181252e2e3d3b5d183afbdc033a3958b445eb3e1a0ae65fc3d4f5259f5da6fd"
+checksum = "ca001d746947c7249ed9d332a10f7a59daedbafeb0ec68c5c18a7db7a93f6ccc"
 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 = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78693fcdd618e0fc34af59c6b8efa9ac5d58c68df940beff4bedddb6acfe7c27"
+dependencies = [
+ "spin",
+ "wasmi_collections",
+ "wasmi_core",
+ "wasmi_ir",
+ "wasmparser 0.228.0",
+]
+
+[[package]]
+name = "wasmi_collections"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a8be2aa467cf2d29e96ff759472c36eeb44a3c81c67fc9cb76c9a24c519c557"
+dependencies = [
+ "string-interner",
+]
+
+[[package]]
+name = "wasmi_core"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69372d5fda3ea3d1e0aa6603c7888110e0187e88ea17cd8fc2e2df0a0e1f37fa"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "wasmi_ir"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f17b774caa13c618c7244f1ee51fe23c5e7b8538a471fa46d9949779758aed6"
+dependencies = [
+ "wasmi_core",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.228.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4abf1132c1fdf747d56bbc1bb52152400c70f336870f968b85e89ea422198ae3"
+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,47 @@ 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",
+ "xrpl-host-functions",
+]
+
+[[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,9 +1,15 @@
 [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]
-cxx = { version = "1.0.198", features = ["c++20"] }
+cxx = { version = "1.0.199", features = ["c++20"] }
 
 [workspace.package]
 edition = "2024"

crates/README.md

@@ -0,0 +1,120 @@
+# Rust crates
+
+This directory holds the WebAssembly engine that runs Smart Escrow contracts,
+bridged into C++ via `cxxbridge`/the `cxx` crate.
+
+The workspace is built unconditionally — `add_subdirectory(crates)` in the
+top-level `CMakeLists.txt` is not behind an option, and
+`xrpl_wasm_vm_ffi_cxxbridge` is a `PUBLIC` dependency of
+`xrpl.libxrpl.ledger` (see `cmake/XrplCore.cmake`). The Rust toolchain pinned in
+[`rust-toolchain.toml`](../rust-toolchain.toml) is therefore required to build
+`libxrpl` at all; the Nix devshell provides it automatically.
+
+## The crates
+
+Dependencies run in one direction: the ABI crate at the bottom, the engine on
+top of it, and the two bridges at the edge.
+
+### `xrpl-host-functions`
+
+The wasm host ABI, declared exactly once. A `host_functions!` block at the
+bottom of `src/lib.rs` generates the `HostFunctions` trait a host implements and
+the `HostFunctionSpec` table a wasm engine registers from. Only the vocabulary
+the declarations are written in — `HostError`, `HostResult`, `TraceDataType`,
+`HASH_LEN` — is hand-written.
+
+**Add or change a host function here**, never in the engine or the bridge: the
+expansion names nothing this file does not, so neither side of the FFI boundary
+gets to restate a signature.
+
+`no_std`, because this crate is also what a guest contract links against.
+
+### `xrpl-host-functions-macros`
+
+The proc macro behind that block, plus the `wasmi_glue!` marshalling it
+generates. An implementation detail of the crate above — nothing else should
+depend on it.
+
+The dev-dependency back on `xrpl-host-functions` is a deliberate cycle: the
+doctests declare host functions returning `HostResult`, which the facade crate
+hand-writes. Cargo allows it because dev-dependencies sit outside the library
+build graph.
+
+### `xrpl-wasm-vm`
+
+The engine itself, on `wasmi`: preflight validation (`preflight/`), gas
+metering and execution (`vm.rs`), and host-call dispatch (`abi.rs`, `args.rs`,
+`register.rs`).
+
+Two lint decisions are load-bearing, both because this is a consensus path:
+
+- `forbid(unsafe_code)`, so "every guest access reaches linear memory only
+  through wasmi's bounds-checked slice operations" is a property rather than a
+  claim.
+- The truncating, wrapping and sign-losing cast lints are `deny` and each
+  remaining cast is argued for at its site — a bad cast here changes what a
+  contract is charged or told.
+
+It pins `wasmi` with `default-features = false` deliberately. wasmi's `wat`
+feature is on by default and makes `Module::new` accept text as readily as
+binary, which would turn a transaction's validity into a build flag.
+
+Not bridged to C++ directly; it reaches `xrpld` through `xrpl-wasm-vm-ffi`.
+
+### `xrpl-wasm-vm-ffi`
+
+The cxx bridge into `xrpld`. Three crossings:
+
+- **In:** C++ calls `run_escrow`, once per escrow finish.
+- **Back out:** that run's host calls leave through the C++ `HostContext`, which
+  `CxxHost` presents to the engine as an ordinary `HostFunctions` implementor.
+- **In only:** C++ screens a module with `check_escrow`. Screening needs no
+  host, so nothing comes back out.
+
+The C++ side is `src/libxrpl/tx/wasm/WasmVM.cpp` and
+`src/libxrpl/tx/wasm/HostContext.cpp`.
+
+**Neither language may unwind into the other**, and the two halves are not
+symmetric:
+
+- A **Rust panic** is caught here, by `guarded`. Letting one reach C++ is
+  undefined behaviour, and `[profile.release]` enables overflow checks, so this
+  is a live path rather than a formality.
+- A **C++ exception** is stopped on the C++ side: every `HostContext` method is
+  `noexcept` and catches its own. That is what makes `guarded` sufficient.
+
+Everything hand-written here is private, so `cargo doc` needs
+`--document-private-items` to show any of it. That is also why this crate,
+unlike `xrpl-wasm-vm`, does not `deny(unreachable_pub)` — cxx's expansion is
+`pub` throughout by necessity.
+
+### `xrpl-wasm-testkit`
+
+**Test-only.** Assembles WebAssembly text for the C++ test suite, and exposes
+the gas price of each host function by its guest import name for the C++ gas
+benchmarks (read through the bridge rather than transcribed into C++, so the
+numbers cannot drift silently).
+
+A crate of its own rather than an entry on `xrpl-wasm-vm-ffi`, and the
+separation is the point: 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 text assembler in the
+shipped node" holds by the link graph rather than by a flag someone can flip.
+
+## Testing
+
+```bash
+cargo test --manifest-path crates/Cargo.toml --workspace
+```
+
+CI uses `cargo nextest`. This is independent of the CMake build.
+
+One gap that command does not cover: it never compiles `xrpl-host-functions`
+with its `wasmi_glue` feature **off**, because `xrpl-wasm-vm` enables the
+feature and Cargo unifies features across a workspace build. The feature-off
+configuration is the one a guest contract sees, so after touching that crate
+also run:
+
+```bash
+cargo check -p xrpl-host-functions --manifest-path crates/Cargo.toml
+```

crates/hello_world/Cargo.toml

@@ -1,13 +0,0 @@
-[package]
-name = "rs-hello_world"
-version = "0.1.0"
-edition.workspace = true
-
-[lib]
-crate-type = ["staticlib"]
-
-[dependencies]
-cxx.workspace = true
-
-[lints]
-workspace = true

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,21 @@
+[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 doctest declares host functions returning `HostResult`, which the facade
+# crate hand-writes. Cargo allows this cycle because dev-dependencies are outside
+# the library build graph.
+[dev-dependencies]
+xrpl-host-functions.path = "../xrpl-host-functions"
+
+[lints]
+workspace = true

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

@@ -0,0 +1,33 @@
+/// 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
+    })
+}
+
+/// `value`, or the folded diagnostics if any were recorded.
+pub(crate) fn into_result<T>(value: T, errors: Vec<syn::Error>) -> syn::Result<T> {
+    match combine(errors) {
+        Some(error) => Err(error),
+        None => Ok(value),
+    }
+}
+
+/// `result`'s value, or `None` with its error filed in `errors` — so a check that
+/// yields a value can be reported like one that yields nothing, and the caller
+/// keeps going.
+pub(crate) fn record<T>(result: syn::Result<T>, errors: &mut Vec<syn::Error>) -> Option<T> {
+    match result {
+        Ok(value) => Some(value),
+        Err(error) => {
+            errors.push(error);
+            None
+        }
+    }
+}

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

@@ -0,0 +1,472 @@
+//! The wasmi registration, generated from the declarations the ABI table is
+//! generated from — so the closure a guest links against cannot disagree with the
+//! signature preflight screens it by.
+//!
+//! Emitted as a `macro_rules!` rather than as the registration itself, because the
+//! crate the expansion lands in is `no_std`, zero-dependency and links into the
+//! guest, and a `macro_rules!` body is inert tokens until someone expands it.
+//!
+//! The body therefore resolves in two crates at once and names nothing free:
+//! `$crate` is the ABI crate, `$env` the module the caller passes in, and every
+//! other path starts at `::wasmi` or `::core`. `$env` is matched as an `ident`
+//! because `$env:path` used as `$env::Foo` is `error: missing angle brackets in
+//! associated item path`.
+//!
+//! The one file that knows an engine's calling convention: how a region arrives as
+//! two wasm parameters, where the gas charge goes, and which helper a result-less
+//! function takes. A second engine would be a second file like it.
+
+use proc_macro2::TokenStream;
+use quote::{ToTokens, quote};
+
+use crate::lowering::{ResultType, WasmValType};
+use crate::parsed_host_function::{Param, ParsedHostFunction};
+
+/// The `wasmi_glue!` macro: the trait a VM implements one body per host function
+/// in, and the registration that hands each of them to a `Linker`.
+pub(crate) fn wasmi_glue(functions: &[ParsedHostFunction]) -> TokenStream {
+    let bodies = functions.iter().map(body_declaration);
+    let registrations = functions.iter().map(registration);
+    let assertions = charging_assertions();
+    let env = env();
+
+    quote! {
+        /// Expands to the wasmi glue for this ABI: the `HostFunctionBodies` trait
+        /// and `register_host_functions`, at the scope it is called in. A
+        /// declaration added to the ABI is then a missing trait item rather than a
+        /// forgotten registration.
+        ///
+        /// `$env` names a module holding everything the expansion reaches for on
+        /// the engine's side, since this crate can name none of it: the store type
+        /// `VmState`, the charging helpers `charged` and `charged_unreported` with
+        /// their `CallResult`, and the argument types `InBytes`, `InStr`, `InU32`,
+        /// `OutBytes` and `TraceCode`.
+        ///
+        /// ```ignore
+        /// mod glue_env {
+        ///     pub(crate) use crate::abi::{CallResult, charged, charged_unreported};
+        ///     pub(crate) use crate::args::{InBytes, InStr, InU32, OutBytes, TraceCode};
+        ///     pub(crate) use crate::vm::VmState;
+        /// }
+        ///
+        /// xrpl_host_functions::wasmi_glue!(glue_env);
+        /// ```
+        ///
+        /// The module supplies the spellings; the shapes are pinned by the
+        /// expansion. Each argument type implements [`FromWasmRegion`] or
+        /// [`FromWasmScalar`] — which one is the ABI's decision, so a declared
+        /// `u32` is a region — and each charging helper's signature is asserted
+        /// against a `const _`.
+        #[cfg(feature = "wasmi_glue")]
+        #[macro_export]
+        macro_rules! wasmi_glue {
+            ($env:ident) => {
+                /// One body per host function: what the engine runs once the call's
+                /// gas is charged and its arguments are off the wire.
+                ///
+                /// The methods take no receiver, so a registered closure captures
+                /// nothing — which is what satisfies wasmi's
+                /// `Fn + Send + Sync + 'static` bound, and why the implementor
+                /// itself need not be `'static`. A body does not charge gas; the
+                /// generated closure does, so it cannot be forgotten or charged
+                /// twice.
+                pub(crate) trait HostFunctionBodies {
+                    #(#bodies)*
+                }
+
+                /// Register every host function on `linker`, one `func_wrap` per
+                /// declaration, at the ABI's derived wasm signature — so an import
+                /// that passes [`crate::check`] links here by construction.
+                pub(crate) fn register_host_functions<B: HostFunctionBodies>(
+                    linker: &mut ::wasmi::Linker<#env::VmState<'_>>,
+                ) -> ::core::result::Result<(), ::wasmi::errors::LinkerError> {
+                    #(#registrations)*
+                    Ok(())
+                }
+
+                #assertions
+            };
+        }
+    }
+}
+
+/// The macro argument every engine-side path is qualified by.
+fn env() -> TokenStream {
+    quote!($env)
+}
+
+/// The signature of each charging helper, pinned as a `const _` the expansion
+/// carries: the one part of the contract neither `$env` nor the argument traits
+/// state.
+///
+/// Its value is the diagnostic. A changed helper is already a type error at the
+/// call, but there it is failed inference inside a generated closure and here it
+/// is one line stating the signature that was expected.
+fn charging_assertions() -> TokenStream {
+    let env = env();
+    let assertion = |helper: TokenStream, answer: TokenStream| {
+        quote! {
+            const _: fn(
+                &mut ::wasmi::Caller<'_, #env::VmState<'_>>,
+                $crate::HostFunctionSpec,
+                fn(&mut ::wasmi::Caller<'_, #env::VmState<'_>>) -> #env::CallResult<#answer>,
+            ) -> ::core::result::Result<#answer, ::wasmi::Error> = #env::#helper;
+        }
+    };
+
+    let reported = assertion(quote!(charged), quote!(i32));
+    let unreported = assertion(quote!(charged_unreported), quote!(()));
+
+    quote! {
+        #reported
+        #unreported
+    }
+}
+
+/// `fn check_keylet(caller: &mut Caller<'_, $env::VmState<'_>>, account:
+/// $env::InBytes, seq: $env::InU32, out: $env::OutBytes) ->
+/// $env::CallResult<i32>;`
+fn body_declaration(function: &ParsedHostFunction) -> TokenStream {
+    let env = env();
+    let name = &function.signature.ident;
+    let params = function.params().iter().map(|param| {
+        let name = &param.name;
+        let ty = param.ty.argument_type(&env);
+        quote! { #name: #ty }
+    });
+    let answer = answer_type(function.result());
+
+    quote! {
+        fn #name(
+            caller: &mut ::wasmi::Caller<'_, #env::VmState<'_>>,
+            #(#params),*
+        ) -> #answer;
+    }
+}
+
+/// One `linker.func_wrap(…)?;`: the wasm signature as the closure's parameters,
+/// the gas charge around the call, and the body between them.
+fn registration(function: &ParsedHostFunction) -> TokenStream {
+    let env = env();
+    let body = &function.signature.ident;
+    let spec = spec_path(function);
+    let params = function.params().iter().flat_map(closure_params);
+    let arguments = function.params().iter().map(lift);
+    let (answer, charge) = match function.result() {
+        ResultType::BufferLength | ResultType::Value => (quote!(i32), quote!(#env::charged)),
+        ResultType::Nothing => (quote!(()), quote!(#env::charged_unreported)),
+    };
+
+    quote! {
+        linker.func_wrap(
+            $crate::HOST_MODULE,
+            #spec.wasm_name(),
+            |mut caller: ::wasmi::Caller<'_, #env::VmState<'_>>, #(#params),*|
+             -> ::core::result::Result<#answer, ::wasmi::Error> {
+                #charge(&mut caller, #spec, |caller| {
+                    B::#body(caller, #(#arguments),*)
+                })
+            },
+        )?;
+    }
+}
+
+/// `$crate::HostFunctionSpec::CheckKeylet` — the one name the expansion reaches
+/// back into the ABI crate for.
+fn spec_path(function: &ParsedHostFunction) -> TokenStream {
+    let variant = &function.variant;
+    quote! { $crate::HostFunctionSpec::#variant }
+}
+
+/// One declared parameter as the closure declares it: `account_ptr: i32,
+/// account_len: i32`, or `field: i32`.
+///
+/// Names and types both come from the lowering, so the arity a closure is
+/// registered at *is* the derived arity.
+fn closure_params(param: &Param) -> Vec<TokenStream> {
+    param
+        .ty
+        .wasm_names(&param.name)
+        .into_iter()
+        .zip(param.ty.as_wasm_params())
+        .map(|(name, val_type)| {
+            let ty = rust_type(*val_type);
+            quote! { #name: #ty }
+        })
+        .collect()
+}
+
+/// The argument a body is handed, built from the wasm parameters it arrived as:
+/// `<$env::InBytes as $crate::FromWasmRegion>::from_wasm(account_ptr,
+/// account_len)`, or the scalar itself.
+///
+/// Qualified rather than an inherent call, so the arity comes from the trait the
+/// lowering chose: an argument type implementing the other one is an unsatisfied
+/// bound named at the type, where `Ty::from_wasm(a, b)` would be an unrelated
+/// arity error named here.
+fn lift(param: &Param) -> TokenStream {
+    let Some(argument_trait) = param.ty.argument_trait() else {
+        return param.name.to_token_stream();
+    };
+    let ty = param.ty.argument_type(&env());
+    let names = param.ty.wasm_names(&param.name);
+
+    quote! { <#ty as $crate::#argument_trait>::from_wasm(#(#names),*) }
+}
+
+/// What a body answers: the value the guest is told, or nothing at all for the
+/// function whose whole effect is on the host.
+fn answer_type(result: ResultType) -> TokenStream {
+    let env = env();
+    match result {
+        ResultType::BufferLength | ResultType::Value => quote!(#env::CallResult<i32>),
+        ResultType::Nothing => quote!(#env::CallResult<()>),
+    }
+}
+
+/// A wasm value type as a closure parameter spells it — a Rust type, not
+/// [`WasmValType`]'s own `ToTokens`, which spells the ABI crate's variant.
+fn rust_type(val_type: WasmValType) -> TokenStream {
+    match val_type {
+        WasmValType::I32 => quote!(i32),
+        WasmValType::I64 => quote!(i64),
+    }
+}
+
+#[cfg(test)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use super::*;
+    use proc_macro2::{Delimiter, Group, TokenTree};
+    use syn::parse_quote;
+
+    fn parsed(function: syn::TraitItemFn) -> ParsedHostFunction {
+        ParsedHostFunction::parse(function).expect("the declaration should parse")
+    }
+
+    /// The declaration whose declared and wasm parameter lists differ most:
+    /// `account`, `out` and `seq` are a `(ptr, len)` pair each, so three arguments
+    /// to the body and six on the wire.
+    #[test]
+    fn lowers_a_declaration_to_a_body_and_a_registration() {
+        let keylet = parsed(parse_quote! {
+            #[gas = 350]
+            #[wasm_name = "check_id"]
+            fn check_keylet(&self, account: &[u8], seq: u32, out: &mut [u8]) -> HostResult<usize>;
+        });
+
+        assert_eq!(
+            body_declaration(&keylet).to_string(),
+            "fn check_keylet (caller : & mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+             account : $ env :: InBytes , seq : $ env :: InU32 , out : $ env :: OutBytes) \
+             -> $ env :: CallResult < i32 > ;"
+        );
+
+        assert_eq!(
+            registration(&keylet).to_string(),
+            "linker . func_wrap ($ crate :: HOST_MODULE , \
+             $ crate :: HostFunctionSpec :: CheckKeylet . wasm_name () , \
+             | mut caller : :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+             account_ptr : i32 , account_len : i32 , seq_ptr : i32 , seq_len : i32 , \
+             out_ptr : i32 , out_len : i32 | \
+             -> :: core :: result :: Result < i32 , :: wasmi :: Error > \
+             { $ env :: charged (& mut caller , \
+             $ crate :: HostFunctionSpec :: CheckKeylet , | caller | \
+             { B :: check_keylet (caller , \
+             < $ env :: InBytes as $ crate :: FromWasmRegion > \
+             :: from_wasm (account_ptr , account_len) , \
+             < $ env :: InU32 as $ crate :: FromWasmRegion > :: from_wasm (seq_ptr , seq_len) , \
+             < $ env :: OutBytes as $ crate :: FromWasmRegion > \
+             :: from_wasm (out_ptr , out_len)) }) } ,) ? ;"
+        );
+    }
+
+    /// A wasm scalar is passed through as itself, in declaration order: no pair,
+    /// no argument type, and an `i64` that stays one.
+    #[test]
+    fn passes_the_wasm_scalars_through_untouched() {
+        let from_int = parsed(parse_quote! {
+            #[gas = 100]
+            #[wasm_name = "float_from_int"]
+            fn float_from_int(&self, x: i64, out: &mut [u8], mode: i32) -> HostResult<usize>;
+        });
+
+        assert_eq!(
+            body_declaration(&from_int).to_string(),
+            "fn float_from_int (caller : & mut :: wasmi :: Caller < '_ , \
+             $ env :: VmState < '_ >> , \
+             x : i64 , out : $ env :: OutBytes , mode : i32) -> $ env :: CallResult < i32 > ;"
+        );
+
+        let registration = registration(&from_int).to_string();
+        assert!(
+            registration.contains(
+                "| mut caller : :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+                 x : i64 , out_ptr : i32 , out_len : i32 , mode : i32 |"
+            ),
+            "{registration}"
+        );
+        assert!(
+            registration.contains(
+                "B :: float_from_int (caller , x , \
+                 < $ env :: OutBytes as $ crate :: FromWasmRegion > \
+                 :: from_wasm (out_ptr , out_len) , mode)"
+            ),
+            "{registration}"
+        );
+    }
+
+    /// The function that answers nothing takes the other charging helper, derived
+    /// from its declared `HostResult<()>` rather than named as a special case.
+    /// Its `TraceCode` is also the only place `FromWasmScalar` is reached for.
+    #[test]
+    fn a_declaration_that_answers_nothing_takes_the_other_charge() {
+        let trace = parsed(trace_declaration());
+
+        assert_eq!(
+            body_declaration(&trace).to_string(),
+            "fn trace (caller : & mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+             msg : $ env :: InStr , data_type : $ env :: TraceCode , data : $ env :: InBytes) \
+             -> $ env :: CallResult < () > ;"
+        );
+
+        let registration = registration(&trace).to_string();
+        assert!(
+            registration.contains(":: core :: result :: Result < () , :: wasmi :: Error >"),
+            "{registration}"
+        );
+        assert!(
+            registration.contains("$ env :: charged_unreported (& mut caller"),
+            "{registration}"
+        );
+        assert!(
+            registration.contains(
+                "B :: trace (caller , \
+                 < $ env :: InStr as $ crate :: FromWasmRegion > :: from_wasm (msg_ptr , msg_len) , \
+                 < $ env :: TraceCode as $ crate :: FromWasmScalar > :: from_wasm (data_type) , \
+                 < $ env :: InBytes as $ crate :: FromWasmRegion > \
+                 :: from_wasm (data_ptr , data_len))"
+            ),
+            "{registration}"
+        );
+    }
+
+    /// The two worlds the macro body resolves in: the ABI crate through `$crate`,
+    /// and one engine by name. `names_no_crate_of_its_own` holds the ABI half of
+    /// the expansion to naming neither.
+    #[test]
+    fn reaches_the_abi_crate_through_dollar_crate_and_the_engine_by_name() {
+        let glue = code(wasmi_glue(&[parsed(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+        })]));
+
+        assert!(
+            glue.contains("$ crate :: HostFunctionSpec :: GetLedgerSqn"),
+            "{glue}"
+        );
+        assert!(glue.contains("$ crate :: HOST_MODULE"), "{glue}");
+        assert!(glue.contains(":: wasmi :: Linker"), "{glue}");
+        assert!(!glue.contains("xrpl_host_functions"), "{glue}");
+    }
+
+    /// Every engine-side item is reached through the module the macro is handed: a
+    /// bare name would resolve against whatever the call site has in scope.
+    ///
+    /// `charged` covers `charged_unreported`, being its prefix.
+    #[test]
+    fn names_the_engine_s_own_items_only_through_the_module_it_is_handed() {
+        let glue = code(wasmi_glue(&[
+            parsed(trace_declaration()),
+            parsed(parse_quote! {
+                #[gas = 350]
+                #[wasm_name = "check_id"]
+                fn check_keylet(&self, account: &[u8], seq: u32, out: &mut [u8])
+                    -> HostResult<usize>;
+            }),
+        ]));
+
+        for item in [
+            "VmState",
+            "CallResult",
+            "charged",
+            "InBytes",
+            "InStr",
+            "InU32",
+            "OutBytes",
+            "TraceCode",
+        ] {
+            for (index, _) in glue.match_indices(item) {
+                assert!(
+                    glue[..index].ends_with("$ env :: "),
+                    "`{item}` named outside `$env`: {glue}"
+                );
+            }
+        }
+    }
+
+    /// The charging helpers' signatures, which nothing else in the contract
+    /// states.
+    #[test]
+    fn pins_both_charging_helpers_signatures() {
+        assert_eq!(
+            charging_assertions().to_string(),
+            "const _ : fn (& mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+             $ crate :: HostFunctionSpec , \
+             fn (& mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >>) \
+             -> $ env :: CallResult < i32 > ,) \
+             -> :: core :: result :: Result < i32 , :: wasmi :: Error > = $ env :: charged ; \
+             const _ : fn (& mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >> , \
+             $ crate :: HostFunctionSpec , \
+             fn (& mut :: wasmi :: Caller < '_ , $ env :: VmState < '_ >>) \
+             -> $ env :: CallResult < () > ,) \
+             -> :: core :: result :: Result < () , :: wasmi :: Error > \
+             = $ env :: charged_unreported ;"
+        );
+    }
+
+    fn trace_declaration() -> syn::TraitItemFn {
+        parse_quote! {
+            #[gas = 30]
+            #[wasm_name = "trace"]
+            fn trace(&self, msg: &str, data_type: TraceDataType, data: &[u8]) -> HostResult<()>;
+        }
+    }
+
+    /// The expansion's code alone. `to_string` renders a doc comment as a
+    /// `#[doc = "…"]` literal, and the macro's own documentation names the very
+    /// items the scans above look for.
+    fn code(tokens: TokenStream) -> String {
+        fn is_doc(tree: Option<&TokenTree>) -> bool {
+            let Some(TokenTree::Group(group)) = tree else {
+                return false;
+            };
+            group.delimiter() == Delimiter::Bracket
+                && matches!(group.stream().into_iter().next(),
+                            Some(TokenTree::Ident(ident)) if ident == "doc")
+        }
+
+        fn strip(tokens: TokenStream) -> TokenStream {
+            let mut trees = tokens.into_iter().peekable();
+            let mut kept = Vec::new();
+            while let Some(tree) = trees.next() {
+                match tree {
+                    TokenTree::Punct(ref punct)
+                        if punct.as_char() == '#' && is_doc(trees.peek()) =>
+                    {
+                        trees.next();
+                    }
+                    TokenTree::Group(group) => kept.push(TokenTree::Group(Group::new(
+                        group.delimiter(),
+                        strip(group.stream()),
+                    ))),
+                    other => kept.push(other),
+                }
+            }
+            kept.into_iter().collect()
+        }
+
+        strip(tokens).to_string()
+    }
+}

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

@@ -0,0 +1,496 @@
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+
+mod errors;
+mod glue;
+mod lowering;
+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 declarations refer to and holds the one declaration
+/// block.
+///
+/// # What it generates
+///
+/// Four items, in the scope the block is written in:
+///
+/// - `pub trait HostFunctions`: one method per declaration, emitted verbatim —
+///   receiver, parameters, return type and doc comment exactly as written. An
+///   execution environment implements it; the rest of the expansion does not
+///   mention it.
+/// - `pub enum HostFunctionSpec`: one variant per declaration, named by
+///   PascalCasing the function name (`get_ledger_sqn` becomes `GetLedgerSqn`) and
+///   carrying that declaration's doc comment. Its `const fn wasm_name`, `gas`,
+///   `wasm_params` and `wasm_result` are the ABI metadata, and `ALL` is every
+///   variant in declaration order — what a wasm engine iterates to build its
+///   import table.
+/// - `struct HostFnSpec`: private, one row of that metadata table. It exists only
+///   so those accessors read from a single `match` over the declarations, and
+///   never appears in a signature a caller can name.
+/// - `macro_rules! wasmi_glue`: the registration for a wasmi engine, emitted as a
+///   macro rather than as code because it names an engine this crate must not
+///   depend on. Inert until expanded — see its own documentation.
+///
+/// The wasm signature is derived from the declared types rather than stated a
+/// second time: `i32` and `i64` are the wasm scalars spelled as themselves, every
+/// other parameter type is marshalled through a `(ptr, len)` pair or an `i32`
+/// code, and the result comes from the `HostResult<T>` success type. The glue is
+/// generated from that same derivation, so the closure a guest links against and
+/// the signature it is screened by are one statement.
+///
+/// Outside the glue's body the expansion builds only `Self::Variant` and
+/// `WasmValType` paths, so the block compiles wherever the types it names —
+/// `HostResult` and `WasmValType` — resolve.
+///
+/// ```
+/// use xrpl_host_functions::{HostResult, WasmValType};
+/// 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<()>;
+/// }
+///
+/// // The trait's methods are the declarations, down to the `&self` receiver the
+/// // VM calls the host through.
+/// fn ledger_sqn(host: &dyn HostFunctions, out: &mut [u8]) -> HostResult<usize> {
+///     host.get_ledger_sqn(out)
+/// }
+///
+/// // The metadata is a `const` table, so gas and import names are available at
+/// // compile time rather than looked up at run time.
+/// const TRACE_GAS: u64 = HostFunctionSpec::TraceNum.gas();
+/// assert_eq!(TRACE_GAS, 500);
+///
+/// assert_eq!(HostFunctionSpec::GetLedgerSqn.wasm_name(), "ldgr_index");
+/// assert_eq!(
+///     HostFunctionSpec::ALL,
+///     &[HostFunctionSpec::GetLedgerSqn, HostFunctionSpec::TraceNum],
+/// );
+///
+/// // So is the wasm signature: `out: &mut [u8]` is the pair `(ptr, len)`, and
+/// // `HostResult<usize>` answers the length written to it.
+/// assert_eq!(
+///     HostFunctionSpec::GetLedgerSqn.wasm_params(),
+///     &[WasmValType::I32, WasmValType::I32],
+/// );
+/// assert_eq!(
+///     HostFunctionSpec::GetLedgerSqn.wasm_result(),
+///     Some(WasmValType::I32),
+/// );
+///
+/// // `trace_num` answers nothing at all, so its import has no result.
+/// assert_eq!(
+///     HostFunctionSpec::TraceNum.wasm_params(),
+///     &[WasmValType::I32, WasmValType::I32, WasmValType::I64],
+/// );
+/// assert_eq!(HostFunctionSpec::TraceNum.wasm_result(), None);
+/// ```
+///
+/// A declaration must be a plain `fn` taking `&self`, with no body and no
+/// generics: it maps to exactly one wasm import signature. Its parameters must be
+/// `i32`, `i64`, `u32`, `&[u8]`, `&mut [u8]`, `&str` or `TraceDataType`, and it
+/// must return `HostResult<usize>` if it writes an output region,
+/// `HostResult<i32>` if it answers a value directly, or `HostResult<()>` if it
+/// answers nothing. 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 functions = parse_block(input)?;
+    let abi = abi_items(&functions);
+    let glue = glue::wasmi_glue(&functions);
+
+    Ok(quote! {
+        #abi
+        #glue
+    })
+}
+
+/// Every declaration in the block, parsed and checked against each other, or
+/// every mistake in it.
+fn parse_block(input: TokenStream) -> syn::Result<Vec<ParsedHostFunction>> {
+    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(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
+}
+
+/// The ABI itself: the trait a host implements and the table everything else
+/// reads. `glue::wasmi_glue` is the other half of the expansion.
+fn abi_items(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.
+        pub trait HostFunctions {
+            #(#trait_methods)*
+        }
+
+        /// One row of the ABI table: what [`HostFunctionSpec`]'s accessors
+        /// read from.
+        ///
+        /// Private, and the only reason it exists is to keep all of them fed
+        /// from a single `match` over the declarations.
+        struct HostFnSpec {
+            name: &'static str,
+            gas: u64,
+            wasm_params: &'static [WasmValType],
+            wasm_result: Option<WasmValType>,
+        }
+
+        /// 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
+            }
+
+            /// The wasm parameters this function is imported with, in wire
+            /// order — the list a guest's import must match, which the
+            /// declaration's own parameter list is not: a declared parameter
+            /// marshalled through a `(ptr, len)` region is two of these.
+            ///
+            /// Usable in `const` context, so import lists can be built at
+            /// compile time.
+            pub const fn wasm_params(self) -> &'static [WasmValType] {
+                self.spec().wasm_params
+            }
+
+            /// The wasm result this function answers with, or `None` for the
+            /// one whose whole effect is on the host. An `i32` where there is
+            /// one, whether the host answered a value or the length of what it
+            /// wrote — the wire does not distinguish those.
+            pub const fn wasm_result(self) -> Option<WasmValType> {
+                self.spec().wasm_result
+            }
+        }
+    }
+}
+
+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)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+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, out: &mut [u8]) -> HostResult<usize>;
+
+            #[gas = 2000]
+            fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize>;
+        })
+        .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()
+    }
+
+    /// The ABI half of the expansion alone: the glue's body is written against
+    /// another crate entirely, so the tests below about what the expansion may
+    /// name are not about it.
+    fn abi_expansion(input: TokenStream) -> String {
+        abi_items(&parse_block(input).expect("the block should parse")).to_string()
+    }
+
+    #[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, out: &mut [u8]) -> HostResult<usize>;
+
+            #[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 , out : & mut [u8]) -> HostResult < usize > ;",
+            "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 , \
+             wasm_params : & 'static [WasmValType] , wasm_result : Option < WasmValType > , }",
+            "const fn spec (self) -> HostFnSpec",
+            // Two wasm parameters for the one declared region, and a result for
+            // the length written to it.
+            "Self :: GetLedgerSqn => HostFnSpec { name : \"ldgr_index\" , gas : 60u64 , \
+             wasm_params : & [WasmValType :: I32 , WasmValType :: I32] , \
+             wasm_result : Some (WasmValType :: I32) , }",
+            "Self :: TraceNum => HostFnSpec { name : \"trace_num\" , gas : 500u64 , \
+             wasm_params : & [WasmValType :: I32 , WasmValType :: I32 , WasmValType :: I64] , \
+             wasm_result : None , }",
+            "pub const fn wasm_name (self) -> & 'static str",
+            "pub const fn gas (self) -> u64",
+            "pub const fn wasm_params (self) -> & 'static [WasmValType]",
+            "pub const fn wasm_result (self) -> Option < WasmValType >",
+            // The fourth item; its contents are `glue`'s own tests.
+            "macro_rules ! wasmi_glue",
+        ] {
+            assert!(generated.contains(expected), "missing {expected:?}");
+        }
+    }
+
+    /// The ABI reaches for nothing outside the crate it lands in, which is what
+    /// lets that crate stay zero-dependency and link into the guest. The glue is
+    /// not held to this — its body names one engine throughout, and `glue`'s own
+    /// tests pin that instead.
+    #[test]
+    fn names_no_crate_of_its_own() {
+        let generated = abi_expansion(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+        });
+
+        assert!(!generated.contains("xrpl_host_functions"), "{generated}");
+
+        // Two roots and no others: `Self::Variant` and `WasmValType::I32`.
+        // Doc comments spell paths without spaces (`Self::ALL`), so they do not
+        // match.
+        for (index, _) in generated.match_indices(" :: ") {
+            let prefix = &generated[..index];
+            assert!(
+                prefix.ends_with("Self") || prefix.ends_with("WasmValType"),
+                "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 = abi_expansion(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+        });
+
+        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<i32>;
+
+            #[gas = 70]
+            #[wasm_name = "b"]
+            fn get_ledger__sqn(&self) -> HostResult<i32>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("`GetLedgerSqn` variant"),
+            "{messages:?}"
+        );
+    }
+}

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

@@ -0,0 +1,488 @@
+//! The wire shape of a declaration: everything a declared Rust type decides — the
+//! wasm value types it lowers to, the names those wasm parameters take, the type a
+//! generated body is handed for it, and which of the ABI's two argument traits
+//! builds that type. Kept as one set of `match` arms because the four must agree.
+//!
+//! The whole mapping, and the only place it is written down: a type no arm here
+//! names is a type the ABI does not have, not one that falls back to something.
+//!
+//! Two rows are worth knowing before reading a declaration:
+//!
+//! - **`u32` is not a scalar.** It is a `(ptr, len)` region holding four
+//!   little-endian bytes, which is how the guest SDK passes a sequence number.
+//! - **`usize` and `i32` results are the same on the wire and not
+//!   interchangeable**: the first is the length of what was written to an output
+//!   region, the second the answer itself.
+//!
+//! Matching is on types as they are spelled — a proc macro resolves nothing, so
+//! `type Bytes = u32; … x: Bytes` is unrecognizable — but on a path's last
+//! segment, so any of these types may be spelled qualified.
+
+use proc_macro2::TokenStream;
+use quote::{ToTokens, format_ident, quote};
+use syn::{Ident, PathArguments, Type, TypePath, TypeReference};
+
+/// What a host function may be handed, and what each costs on the wire.
+///
+/// Declaration order is wasm parameter order, so a reader of a declaration is
+/// reading the import the guest links against.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ParamType {
+    /// `i32`, passed through as itself. Also the spelling for a raw scalar
+    /// whose signedness the ABI does not fix.
+    I32,
+    /// `i64`, passed through as itself.
+    I64,
+    /// `TraceDataType`: an `i32` code the engine resolves to the enum before a
+    /// host sees it.
+    TraceDataType,
+    /// `&[u8]`: a borrowed input region.
+    InBytes,
+    /// `&str`: an input region whose read is also the UTF-8 check.
+    InStr,
+    /// `u32`: an input region holding four little-endian bytes.
+    InU32,
+    /// `&mut [u8]`: the writable output region.
+    OutBytes,
+}
+
+/// The success type of the `HostResult<T>` every declaration returns. These three
+/// are what the ABI has; any other `T` is an error.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ResultType {
+    /// `usize`: the true length of a value written to an output region, which
+    /// the engine turns into the wire's `i32` or into `BufferTooSmall` /
+    /// `DataFieldTooLarge`. Never itself the wire type.
+    BufferLength,
+    /// `i32`: the answer, from a function that writes no region.
+    Value,
+    /// `()`: no wasm result at all — the call's whole effect is on the host, and
+    /// an `Err` reaches the guest in no form.
+    Nothing,
+}
+
+/// The wasm value types this ABI uses, mirroring `xrpl_host_functions::WasmValType`.
+///
+/// Mirrored rather than shared because the dependency runs the other way: the ABI
+/// crate depends on this one, so nothing here can name its types. The [`ToTokens`]
+/// impl below is the whole of the crossing, and emits references to that enum's
+/// variants — so falling out of sync with it is a compile error at the
+/// `host_functions!` call site rather than drift.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum WasmValType {
+    I32,
+    I64,
+}
+
+impl ParamType {
+    /// Recognizes the declared type, or refuses it against its own span.
+    pub(crate) fn parse(ty: &Type) -> syn::Result<Self> {
+        const ALLOWED: &str = "a host function's parameter must be `i32`, `i64`, `u32`, \
+                               `&[u8]`, `&mut [u8]`, `&str` or `TraceDataType`";
+
+        let recognized = match ty {
+            // A lifetime on the reference changes nothing on the wire.
+            Type::Reference(TypeReference {
+                mutability, elem, ..
+            }) => match (mutability, &**elem) {
+                (None, Type::Slice(slice)) if is_named(&slice.elem, "u8") => Some(Self::InBytes),
+                (Some(_), Type::Slice(slice)) if is_named(&slice.elem, "u8") => {
+                    Some(Self::OutBytes)
+                }
+                (None, elem) if is_named(elem, "str") => Some(Self::InStr),
+                _ => None,
+            },
+            _ => match last_path_segment(ty) {
+                Some(name) if name == "i32" => Some(Self::I32),
+                Some(name) if name == "i64" => Some(Self::I64),
+                Some(name) if name == "u32" => Some(Self::InU32),
+                Some(name) if name == "TraceDataType" => Some(Self::TraceDataType),
+                _ => None,
+            },
+        };
+
+        recognized.ok_or_else(|| syn::Error::new_spanned(ty, ALLOWED))
+    }
+
+    /// The wasm parameters this declared type lowers to, in order. `InBytes` and
+    /// `OutBytes` lower alike, so a region's direction survives only in the
+    /// variant.
+    pub(crate) fn as_wasm_params(self) -> &'static [WasmValType] {
+        match self {
+            Self::I32 | Self::TraceDataType => &[WasmValType::I32],
+            Self::I64 => &[WasmValType::I64],
+            Self::InBytes | Self::InStr | Self::InU32 | Self::OutBytes => {
+                &[WasmValType::I32, WasmValType::I32]
+            }
+        }
+    }
+
+    /// What a declaration calls each of those wasm parameters: the declared name
+    /// for a scalar, and `{name}_ptr`/`{name}_len` for the pair a region lowers
+    /// to.
+    ///
+    /// **It must answer as many names as [`Self::as_wasm_params`] answers types**,
+    /// since the generated closure declares them one against the other — hence the
+    /// matching arms, and `lowers_every_declared_parameter_type`'s row-by-row
+    /// length check.
+    pub(crate) fn wasm_names(self, name: &Ident) -> Vec<Ident> {
+        match self {
+            Self::I32 | Self::I64 | Self::TraceDataType => vec![name.clone()],
+            Self::InBytes | Self::InStr | Self::InU32 | Self::OutBytes => {
+                vec![format_ident!("{name}_ptr"), format_ident!("{name}_len")]
+            }
+        }
+    }
+
+    /// The type a generated body takes this parameter as: a wasm scalar spelled as
+    /// itself, everything else the argument type carrying its shape and direction —
+    /// which is what makes an input region used as an output one a compile error
+    /// naming both.
+    ///
+    /// The argument types are the engine's, so `vm` is the path they are reached
+    /// under; which types need it is decided here, a wasm scalar being `i32` under
+    /// every engine.
+    pub(crate) fn argument_type(self, vm: &TokenStream) -> TokenStream {
+        match self {
+            Self::I32 => quote!(i32),
+            Self::I64 => quote!(i64),
+            Self::TraceDataType => quote!(#vm::TraceCode),
+            Self::InBytes => quote!(#vm::InBytes),
+            Self::InStr => quote!(#vm::InStr),
+            Self::InU32 => quote!(#vm::InU32),
+            Self::OutBytes => quote!(#vm::OutBytes),
+        }
+    }
+
+    /// Which of the ABI's two argument traits builds this parameter's argument
+    /// type, or `None` for a wasm scalar, which reaches a body as itself.
+    ///
+    /// The arity is the whole of the distinction — `FromWasmRegion` takes the two
+    /// of a `(ptr, len)` pair, `FromWasmScalar` the one of a code — so this answers
+    /// alongside [`Self::as_wasm_params`] rather than from a predicate elsewhere.
+    pub(crate) fn argument_trait(self) -> Option<TokenStream> {
+        match self {
+            Self::I32 | Self::I64 => None,
+            Self::TraceDataType => Some(quote!(FromWasmScalar)),
+            Self::InBytes | Self::InStr | Self::InU32 | Self::OutBytes => {
+                Some(quote!(FromWasmRegion))
+            }
+        }
+    }
+
+    /// Whether this parameter is a region the host writes to — what
+    /// [`ResultType::BufferLength`] is the length *of*.
+    pub(crate) fn is_out_region(self) -> bool {
+        matches!(self, Self::OutBytes)
+    }
+}
+
+impl ResultType {
+    /// Recognizes the success type of a declaration's `HostResult<T>`, or
+    /// refuses it against its own span.
+    pub(crate) fn parse(success: &Type) -> syn::Result<Self> {
+        const ALLOWED: &str = "a host function must return `HostResult<usize>` for a value it \
+                               writes to an output region, `HostResult<i32>` for one it answers \
+                               directly, or `HostResult<()>` for none at all";
+
+        if let Type::Tuple(tuple) = success
+            && tuple.elems.is_empty()
+        {
+            return Ok(Self::Nothing);
+        }
+
+        match last_path_segment(success) {
+            Some(name) if name == "usize" => Ok(Self::BufferLength),
+            Some(name) if name == "i32" => Ok(Self::Value),
+            _ => Err(syn::Error::new_spanned(success, ALLOWED)),
+        }
+    }
+
+    /// The generated table's `wasm_result` field: `Some(WasmValType::I32)`, or
+    /// `None` for the function that answers nothing.
+    ///
+    /// Spelled out here rather than left to `quote`'s `Option` impl, which emits
+    /// nothing at all for `None`.
+    pub(crate) fn wasm_result_tokens(self) -> TokenStream {
+        match self.as_wasm_result() {
+            Some(val_type) => quote! { Some(#val_type) },
+            None => quote! { None },
+        }
+    }
+
+    /// Whether the value reaches the guest as the length of what was written to
+    /// an output region.
+    pub(crate) fn is_buffer_length(self) -> bool {
+        matches!(self, Self::BufferLength)
+    }
+
+    /// The wasm result, which does not distinguish a length from a value.
+    fn as_wasm_result(self) -> Option<WasmValType> {
+        match self {
+            Self::BufferLength | Self::Value => Some(WasmValType::I32),
+            Self::Nothing => None,
+        }
+    }
+}
+
+/// `WasmValType::I32` — the ABI crate's variant, named but never defined here.
+impl ToTokens for WasmValType {
+    fn to_tokens(&self, tokens: &mut TokenStream) {
+        tokens.extend(match self {
+            Self::I32 => quote! { WasmValType::I32 },
+            Self::I64 => quote! { WasmValType::I64 },
+        });
+    }
+}
+
+/// The last segment of a plain path type, when it carries no generic arguments:
+/// `i32`, `core::primitive::i32` and `TraceDataType` all answer their own name,
+/// `Vec<u8>` and `[u8; 4]` nothing.
+fn last_path_segment(ty: &Type) -> Option<&Ident> {
+    let Type::Path(TypePath {
+        qself: None, path, ..
+    }) = ty
+    else {
+        return None;
+    };
+    let last = path.segments.last()?;
+    matches!(last.arguments, PathArguments::None).then_some(&last.ident)
+}
+
+/// Whether `ty` is the named primitive, however it is spelled.
+fn is_named(ty: &Type, name: &str) -> bool {
+    last_path_segment(ty).is_some_and(|segment| segment == name)
+}
+
+#[cfg(test)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use super::*;
+    use syn::parse_quote;
+
+    use WasmValType::{I32, I64};
+
+    /// Every declared parameter type and everything it decides: what it costs on
+    /// the wire, what a body is handed for it, and which trait builds that.
+    ///
+    /// The names are asserted by length rather than spelling, since a type
+    /// answering fewer names than value types is the one way these answers can
+    /// contradict each other.
+    #[test]
+    fn lowers_every_declared_parameter_type() {
+        let mapping: [(Type, &[WasmValType], &str, Option<&str>); 7] = [
+            (parse_quote!(i32), &[I32], "i32", None),
+            (parse_quote!(i64), &[I64], "i64", None),
+            (
+                parse_quote!(TraceDataType),
+                &[I32],
+                "vm :: TraceCode",
+                Some("FromWasmScalar"),
+            ),
+            (
+                parse_quote!(&[u8]),
+                &[I32, I32],
+                "vm :: InBytes",
+                Some("FromWasmRegion"),
+            ),
+            (
+                parse_quote!(&str),
+                &[I32, I32],
+                "vm :: InStr",
+                Some("FromWasmRegion"),
+            ),
+            (
+                parse_quote!(u32),
+                &[I32, I32],
+                "vm :: InU32",
+                Some("FromWasmRegion"),
+            ),
+            (
+                parse_quote!(&mut [u8]),
+                &[I32, I32],
+                "vm :: OutBytes",
+                Some("FromWasmRegion"),
+            ),
+        ];
+        let declared_name = format_ident!("seq");
+        let vm = quote!(vm);
+
+        for (declared, wasm, argument, argument_trait) in mapping {
+            let param = ParamType::parse(&declared)
+                .unwrap_or_else(|_| panic!("`{}` should be a parameter type", quoted(&declared)));
+
+            assert_eq!(param.as_wasm_params(), wasm, "`{}`", quoted(&declared));
+            assert_eq!(
+                param.argument_type(&vm).to_string(),
+                argument,
+                "`{}`",
+                quoted(&declared)
+            );
+            assert_eq!(
+                param
+                    .argument_trait()
+                    .map(|name| name.to_string())
+                    .as_deref(),
+                argument_trait,
+                "`{}`",
+                quoted(&declared)
+            );
+            assert_eq!(
+                param.wasm_names(&declared_name).len(),
+                wasm.len(),
+                "one name per wasm parameter: `{}`",
+                quoted(&declared)
+            );
+        }
+    }
+
+    /// A region's two wasm parameters are named off the declaration, so the
+    /// generated closure reads as the declaration does.
+    #[test]
+    fn names_a_region_s_pair_after_the_declared_parameter() {
+        let seq = format_ident!("seq");
+
+        let names = |declared: Type| {
+            ParamType::parse(&declared)
+                .expect("a parameter type")
+                .wasm_names(&seq)
+                .iter()
+                .map(Ident::to_string)
+                .collect::<Vec<_>>()
+        };
+
+        assert_eq!(names(parse_quote!(u32)), ["seq_ptr", "seq_len"]);
+        assert_eq!(names(parse_quote!(i32)), ["seq"]);
+    }
+
+    /// The two `(ptr, len)` pairs lower alike but are told apart, since only the
+    /// direction says who may write to the region.
+    #[test]
+    fn keeps_the_regions_apart() {
+        let input: Type = parse_quote!(&[u8]);
+        let output: Type = parse_quote!(&mut [u8]);
+
+        assert!(!ParamType::parse(&input).unwrap().is_out_region());
+        assert!(ParamType::parse(&output).unwrap().is_out_region());
+    }
+
+    /// A type outside the mapping is refused rather than lowered to a guess.
+    #[test]
+    fn refuses_parameter_types_outside_the_mapping() {
+        let outside: [Type; 11] = [
+            parse_quote!(u64),
+            parse_quote!(u8),
+            parse_quote!(usize),
+            parse_quote!(bool),
+            parse_quote!(Vec<u8>),
+            parse_quote!([u8; 4]),
+            parse_quote!(&mut str),
+            parse_quote!(&i32),
+            parse_quote!(&[i32]),
+            parse_quote!(&Foo),
+            parse_quote!(()),
+        ];
+
+        for declared in outside {
+            let Err(error) = ParamType::parse(&declared) else {
+                panic!("`{}` should not be a parameter type", quoted(&declared));
+            };
+            assert!(
+                error.to_string().contains("must be `i32`"),
+                "`{}`: {error}",
+                quoted(&declared)
+            );
+        }
+    }
+
+    /// The three success types, and the wasm result each becomes. `usize` and
+    /// `i32` agree on the wire and are separate rows.
+    #[test]
+    fn lowers_every_success_type() {
+        let mapping: [(Type, ResultType, Option<WasmValType>); 3] = [
+            (parse_quote!(usize), ResultType::BufferLength, Some(I32)),
+            (parse_quote!(i32), ResultType::Value, Some(I32)),
+            (parse_quote!(()), ResultType::Nothing, None),
+        ];
+
+        for (declared, expected, wasm_result) in mapping {
+            let result = ResultType::parse(&declared)
+                .unwrap_or_else(|_| panic!("`{}` should be a success type", quoted(&declared)));
+
+            assert_eq!(result, expected, "`{}`", quoted(&declared));
+            assert_eq!(
+                result.as_wasm_result(),
+                wasm_result,
+                "`{}`",
+                quoted(&declared)
+            );
+        }
+    }
+
+    /// The distinction the wasm result loses: which of the two `i32` results was
+    /// declared decides how the value reaches the guest.
+    #[test]
+    fn tells_a_length_from_a_value() {
+        assert!(ResultType::BufferLength.is_buffer_length());
+        assert!(!ResultType::Value.is_buffer_length());
+        assert!(!ResultType::Nothing.is_buffer_length());
+    }
+
+    #[test]
+    fn refuses_success_types_outside_the_mapping() {
+        let outside: [Type; 6] = [
+            parse_quote!(u32),
+            parse_quote!(i64),
+            parse_quote!(bool),
+            parse_quote!([u8; 32]),
+            parse_quote!(Vec<u8>),
+            parse_quote!((usize, i32)),
+        ];
+
+        for declared in outside {
+            let Err(error) = ResultType::parse(&declared) else {
+                panic!("`{}` should not be a success type", quoted(&declared));
+            };
+            assert!(
+                error
+                    .to_string()
+                    .contains("must return `HostResult<usize>`"),
+                "`{}`: {error}",
+                quoted(&declared)
+            );
+        }
+    }
+
+    /// A qualified spelling is the same type, matching how the return type finds
+    /// `HostResult`.
+    #[test]
+    fn accepts_qualified_spellings() {
+        let qualified: Type = parse_quote!(core::primitive::i32);
+        assert_eq!(ParamType::parse(&qualified).unwrap(), ParamType::I32);
+
+        let qualified: Type = parse_quote!(xrpl_host_functions::TraceDataType);
+        assert_eq!(
+            ParamType::parse(&qualified).unwrap(),
+            ParamType::TraceDataType
+        );
+    }
+
+    /// The emitted tokens name the ABI crate's variants, which is the whole of
+    /// what crosses out of this crate. Pinned here so a break in the mirror is a
+    /// failure with a span rather than a rustc error at the call site.
+    #[test]
+    fn emits_references_to_the_hand_written_variants() {
+        assert_eq!(I32.to_token_stream().to_string(), "WasmValType :: I32");
+        assert_eq!(I64.to_token_stream().to_string(), "WasmValType :: I64");
+
+        assert_eq!(
+            ResultType::BufferLength.wasm_result_tokens().to_string(),
+            "Some (WasmValType :: I32)"
+        );
+        assert_eq!(ResultType::Nothing.wasm_result_tokens().to_string(), "None");
+    }
+
+    fn quoted(ty: &Type) -> String {
+        ty.to_token_stream().to_string()
+    }
+}

crates/xrpl-host-functions/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "xrpl-host-functions"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+xrpl-host-functions-macros.path = "../xrpl-host-functions-macros"
+
+# `wasmi_glue!` and the two argument traits it marshals through are a host's
+# business, and this crate is what a contract links against — so the feature is
+# what keeps `cargo doc` here showing a contract developer only the ABI. It costs
+# nothing either way: a `macro_rules!` is inert and a trait with no impls emits
+# nothing.
+#
+# `xrpl-wasm-vm` enables it and features unify across the graph, so the off
+# configuration is only ever checked by `cargo check -p xrpl-host-functions`,
+# which is in the loop in `tmp/notes/wasm-vm/testing.md` for that reason.
+[features]
+default = []
+wasmi_glue = []
+
+[lints]
+workspace = true

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

@@ -0,0 +1,713 @@
+//! 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.
+//!
+//! Three items cross that split the other way, named by the expansion but by no
+//! declaration: [`WasmValType`], which the derived wasm signatures are spelled in,
+//! and `FromWasmRegion`/`FromWasmScalar`, which `wasmi_glue!` builds a marshalled
+//! argument through.
+//!
+//! 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]
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+
+#[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,
+    SubmitTxnFailure = -21,
+    InvalidState = -22,
+    /// 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,
+}
+
+/// The wasm module name a guest imports these functions under:
+/// `(import "host_lib" "ldgr_index" …)`.
+pub const HOST_MODULE: &str = "host_lib";
+
+/// A wasm value type, as many of them as this ABI uses — the vocabulary the
+/// generated wasm signatures are spelled in, which an engine maps to its own value
+/// types once.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WasmValType {
+    I32,
+    I64,
+}
+
+/// Builds the argument an engine marshals a `(ptr, len)` region into: a declared
+/// `&[u8]`, `&str`, `u32` or `&mut [u8]`. Nothing is checked here — the pair
+/// arrives as the guest sent it, and refusing a malformed region is the engine's
+/// business.
+///
+/// **Kept apart from [`FromWasmScalar`]** rather than folded into one trait with
+/// an associated wasm type, for the diagnostic: the mistake worth catching is an
+/// arity one — a declared `u32` is a region, not a code — and as two traits that
+/// lands as an unsatisfied bound at the offending argument type rather than an
+/// `i32`-against-`(i32, i32)` mismatch at the macro call.
+#[cfg(feature = "wasmi_glue")]
+pub trait FromWasmRegion {
+    fn from_wasm(ptr: i32, len: i32) -> Self;
+}
+
+/// Builds the argument an engine marshals a single `i32` code into: the declared
+/// `TraceDataType`. [`FromWasmRegion`] says why the two are separate traits.
+#[cfg(feature = "wasmi_glue")]
+pub trait FromWasmScalar {
+    fn from_wasm(code: i32) -> Self;
+}
+
+// Two rules hold over every declaration below, and neither is visible at any one of
+// them. They are what lets the wasm signature be read off the declaration.
+//
+// **Declaration order is wasm parameter order.** So `mode` comes after `out` in the
+// float functions, and `data_type` between `trace`'s two regions: the wire's order,
+// not the one a Rust signature would choose.
+//
+// **`i32` and `i64` are the wasm scalars, spelled as themselves; every other type is
+// marshalled.** `&[u8]`/`&str` and `&mut [u8]` are `(ptr, len)` pairs, `TraceDataType`
+// is an `i32` code the engine names before a host sees it, and **`u32` is four
+// little-endian bytes in a region**, not a scalar, which is how the guest SDK passes a
+// sequence number.
+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.
+    #[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. Answers the slot used.
+    #[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).
+    #[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; `NoArray` if the field is not an array.
+    #[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`.
+    #[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`. Answers `1` if the signature
+    /// is valid, `0` if not, or a negative error.
+    #[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.
+    #[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).
+    #[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.
+    #[gas = 350]
+    #[wasm_name = "check_id"]
+    fn check_keylet(&self, account: &[u8], seq: u32, 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.
+    #[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.
+    #[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.
+    #[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.
+    #[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.
+    #[gas = 350]
+    #[wasm_name = "escrow_id"]
+    fn escrow_keylet(&self, account: &[u8], seq: u32, 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.
+    #[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.
+    #[gas = 350]
+    #[wasm_name = "mpt_issuance_id"]
+    fn mptoken_issuance_keylet(
+        &self,
+        issuer: &[u8],
+        seq: u32,
+        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.
+    #[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.
+    #[gas = 350]
+    #[wasm_name = "nft_offer_id"]
+    fn nftoken_offer_keylet(
+        &self,
+        account: &[u8],
+        seq: u32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Offer`, computed from the 20-byte owner account and
+    /// its sequence number.
+    #[gas = 350]
+    #[wasm_name = "offer_id"]
+    fn offer_keylet(&self, account: &[u8], seq: u32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Oracle`, computed from the 20-byte owner account and
+    /// its document id.
+    #[gas = 350]
+    #[wasm_name = "oracle_id"]
+    fn oracle_keylet(&self, account: &[u8], doc_id: u32, 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.
+    #[gas = 350]
+    #[wasm_name = "paychan_id"]
+    fn paychannel_keylet(
+        &self,
+        account: &[u8],
+        destination: &[u8],
+        seq: u32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PermissionedDomain`, computed from the 20-byte owner
+    /// account and its sequence number.
+    #[gas = 350]
+    #[wasm_name = "permissioned_domain_id"]
+    fn permissioned_domain_keylet(
+        &self,
+        account: &[u8],
+        seq: u32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `SignerList`, computed from its 20-byte owner account.
+    #[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.
+    #[gas = 350]
+    #[wasm_name = "ticket_id"]
+    fn ticket_keylet(&self, account: &[u8], seq: u32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Vault`, computed from the 20-byte owner account and its
+    /// sequence number.
+    #[gas = 350]
+    #[wasm_name = "vault_id"]
+    fn vault_keylet(&self, account: &[u8], seq: u32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Sponsorship`, computed from the 20-byte sponsor account
+    /// and the 20-byte sponsee account.
+    #[gas = 350]
+    #[wasm_name = "sponsorship_id"]
+    fn sponsorship_keylet(
+        &self,
+        sponsor: &[u8],
+        sponsee: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `LoanBroker`, computed from the 20-byte owner account and
+    /// its sequence number.
+    #[gas = 350]
+    #[wasm_name = "loan_broker_id"]
+    fn loan_broker_keylet(&self, owner: &[u8], seq: u32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Loan`, computed from the 32-byte id of its `LoanBroker`
+    /// and the loan's sequence number.
+    #[gas = 350]
+    #[wasm_name = "loan_id"]
+    fn loan_keylet(
+        &self,
+        loan_broker_id: &[u8],
+        loan_seq: u32,
+        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.
+    #[gas = 30]
+    #[wasm_name = "trace"]
+    fn trace(&self, msg: &str, data_type: TraceDataType, data: &[u8]) -> HostResult<()>;
+
+    /// Stores `data` as the current object's data field, replacing whatever was there,
+    /// and returns the number of bytes stored; `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`.
+    #[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).
+    #[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), as 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).
+    #[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).
+    #[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), as 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`.
+    #[gas = 100]
+    #[wasm_name = "float_from_int"]
+    fn float_from_int(&self, x: i64, out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// A float built from the unsigned integer in the 8-byte region `x` under rounding
+    /// `mode`.
+    #[gas = 130]
+    #[wasm_name = "float_from_uint"]
+    fn float_from_uint(&self, x: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// A float built from the serialized `STAmount` in `amount` under rounding `mode`.
+    #[gas = 150]
+    #[wasm_name = "float_from_stamount"]
+    fn float_from_stamount(&self, amount: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// A float built from the serialized `STNumber` in `number` under rounding `mode`.
+    #[gas = 150]
+    #[wasm_name = "float_from_stnumber"]
+    fn float_from_stnumber(&self, number: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float `x` rounded to a signed integer under rounding `mode`, as eight
+    /// little-endian bytes.
+    #[gas = 130]
+    #[wasm_name = "float_to_int"]
+    fn float_to_int(&self, x: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float `x` split into its mantissa (eight little-endian bytes) and its exponent
+    /// (four little-endian bytes), each written to its own output region.
+    #[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`.
+    #[gas = 100]
+    #[wasm_name = "float_from_mant_exp"]
+    fn float_from_mant_exp(
+        &self,
+        mantissa: i64,
+        exponent: i32,
+        out: &mut [u8],
+        mode: i32,
+    ) -> 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`.
+    #[gas = 80]
+    #[wasm_name = "float_cmp"]
+    fn float_compare(&self, x: &[u8], y: &[u8]) -> HostResult<i32>;
+
+    /// The float sum `x + y` under rounding `mode`.
+    #[gas = 160]
+    #[wasm_name = "float_add"]
+    fn float_add(&self, x: &[u8], y: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float difference `x - y` under rounding `mode`.
+    #[gas = 160]
+    #[wasm_name = "float_sub"]
+    fn float_subtract(&self, x: &[u8], y: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float product `x * y` under rounding `mode`.
+    #[gas = 300]
+    #[wasm_name = "float_mult"]
+    fn float_multiply(&self, x: &[u8], y: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float quotient `x / y` under rounding `mode`.
+    #[gas = 300]
+    #[wasm_name = "float_div"]
+    fn float_divide(&self, x: &[u8], y: &[u8], out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    /// The float `x` raised to the power `n` under rounding `mode`.
+    #[gas = 5500]
+    #[wasm_name = "float_pow"]
+    fn float_power(&self, x: &[u8], n: i32, out: &mut [u8], mode: i32) -> HostResult<usize>;
+
+    // ------------------------------------------------------------------
+    // Smart contracts
+    //
+    // A contract reaches the parameters it was instantiated and called with, the
+    // data object it keeps per account, and the transactions and events it emits.
+    // A programmable escrow's host implements none of these, so they answer
+    // `Unimplemented` there.
+    // ------------------------------------------------------------------
+
+    /// The contract instance's parameter at `index`, serialized as the type `st_type_id`
+    /// names; `InvalidParams` if the parameter does not hold that type.
+    #[gas = 100]
+    #[wasm_name = "instance_param"]
+    fn instance_param(&self, index: i32, st_type_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The parameter this call was given at `index`, serialized as the type `st_type_id`
+    /// names; `InvalidParams` if the parameter does not hold that type.
+    #[gas = 100]
+    #[wasm_name = "function_param"]
+    fn function_param(&self, index: i32, st_type_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The value `key` holds in the 20-byte `account`'s data object, as its canonical
+    /// field serialization without a leading type byte.
+    #[gas = 500]
+    #[wasm_name = "get_data_object_field"]
+    fn get_data_object_field(&self, account: &[u8], key: &str, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The value `nested_key` holds in the object under `key` in `account`'s data object.
+    #[gas = 500]
+    #[wasm_name = "get_data_nested_object_field"]
+    fn get_data_nested_object_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        nested_key: &str,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The value `key` holds in element `index` of `account`'s data array.
+    #[gas = 500]
+    #[wasm_name = "get_data_array_element_field"]
+    fn get_data_array_element_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        index: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The value `nested_key` holds in element `index` of the array under `key` in
+    /// `account`'s data object.
+    #[gas = 500]
+    #[wasm_name = "get_data_nested_array_element_field"]
+    fn get_data_nested_array_element_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        index: i32,
+        nested_key: &str,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// Stores `value` under `key` in `account`'s data object, replacing whatever was
+    /// there. `value` is a field serialization preceded by its one-byte type.
+    #[gas = 500]
+    #[wasm_name = "set_data_object_field"]
+    fn set_data_object_field(&self, account: &[u8], key: &str, value: &[u8]) -> HostResult<i32>;
+
+    /// Stores `value` under `nested_key` in the object under `key` in `account`'s data
+    /// object. `key` is the outer name.
+    #[gas = 500]
+    #[wasm_name = "set_data_nested_object_field"]
+    fn set_data_nested_object_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        nested_key: &str,
+        value: &[u8],
+    ) -> HostResult<i32>;
+
+    /// Stores `value` under `key` in element `index` of `account`'s data array.
+    #[gas = 500]
+    #[wasm_name = "set_data_array_element_field"]
+    fn set_data_array_element_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        index: i32,
+        value: &[u8],
+    ) -> HostResult<i32>;
+
+    /// Stores `value` under `nested_key` in element `index` of the array under `key` in
+    /// `account`'s data object.
+    #[gas = 500]
+    #[wasm_name = "set_data_nested_array_element_field"]
+    fn set_data_nested_array_element_field(
+        &self,
+        account: &[u8],
+        key: &str,
+        index: i32,
+        nested_key: &str,
+        value: &[u8],
+    ) -> HostResult<i32>;
+
+    /// Starts building a transaction of type `tx_type` and answers its index, or
+    /// `SubmitTxnFailure` if a contract may not emit that type.
+    #[gas = 200]
+    #[wasm_name = "build_txn"]
+    fn build_txn(&self, tx_type: i32) -> HostResult<i32>;
+
+    /// Sets the field `field` names on the transaction being built at `index` to `data`,
+    /// which is that field's serialization.
+    #[gas = 200]
+    #[wasm_name = "add_txn_field"]
+    fn add_txn_field(&self, index: i32, field: i32, data: &[u8]) -> HostResult<i32>;
+
+    /// Applies the transaction built at `index`, writing the resulting TER as four
+    /// little-endian bytes.
+    ///
+    /// The TER is written rather than returned because a `tem`, `tef`, `ter` or `tel`
+    /// code is negative, and a negative result is a `HostError`. A `BufferTooSmall`
+    /// here does not un-apply the transaction: the emit has already happened.
+    #[gas = 500]
+    #[wasm_name = "emit_built_txn"]
+    fn emit_built_txn(&self, index: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// Applies the serialized transaction `txn`, writing the resulting TER as four
+    /// little-endian bytes; `InvalidParams` if `txn` is not a well-formed transaction.
+    /// The TER is written rather than returned for the reason `emit_built_txn` gives.
+    #[gas = 500]
+    #[wasm_name = "emit_txn"]
+    fn emit_txn(&self, txn: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// Records `data` as the event named `name`, for this node's subscribers. `data` is
+    /// a serialized `STJson` object.
+    #[gas = 500]
+    #[wasm_name = "emit_event"]
+    fn emit_event(&self, name: &str, data: &[u8]) -> HostResult<i32>;
+}

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,41 @@
+//! `host_functions!` must work outside the crate that declares the ABI: the only
+//! names its expansion needs are `WasmValType` and the ones the declarations
+//! themselves spell.
+//!
+//! That this crate compiles is also what shows the emitted `wasmi_glue!` costs
+//! nothing to carry: its body names an engine throughout, there is no engine
+//! here, and nobody here expands it.
+
+use xrpl_host_functions::{HostResult, WasmValType};
+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);
+    assert_eq!(HostFunctionSpec::Ping.wasm_params(), &[WasmValType::I32]);
+    assert_eq!(HostFunctionSpec::Ping.wasm_result(), Some(WasmValType::I32));
+}
+
+/// 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,104 @@
+//! 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::SubmitTxnFailure, -21),
+            (HostError::InvalidState, -22),
+            (HostError::InternalFatal, i32::MIN),
+        ]
+    );
+}
+
+/// The guest-facing set is `-1 ..= -22` 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| !(-22..=-1).contains(&error.code()))
+        .collect();
+
+    assert!(outside.is_empty(), "outside -1..=-22: {outside:?}");
+    assert_eq!(shared.len(), 22);
+    assert_eq!(HostError::InternalFatal.code(), i32::MIN);
+    assert_eq!(HostError::ALL.len(), 23);
+}
+
+/// 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.
+///
+/// `-23` 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 [-23, i32::MIN + 1, 0, 1, i32::MAX] {
+        assert_eq!(
+            HostError::from_code(code),
+            HostError::InternalFatal,
+            "{code}"
+        );
+    }
+}

crates/xrpl-wasm-testkit/Cargo.toml

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

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

@@ -0,0 +1,109 @@
+//! 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. 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)]
+#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+
+#[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>>;
+
+        /// The gas a host function is charged before it runs, by its guest import name.
+        ///
+        /// For the C++ gas benchmarks, which measure what a host call actually costs and
+        /// report it against what the table says it costs. Reading the declaration through
+        /// here rather than copying the numbers into C++ is the point: 61 transcribed
+        /// constants would drift from `lib.rs` the first time a price changed, and drift
+        /// silently, because a benchmark has nothing to fail.
+        ///
+        /// Throws `rust::Error` on an unknown name — a typo should fail loudly rather than
+        /// quietly compare against zero.
+        fn host_function_gas(wasm_name: &str) -> Result<u64>;
+    }
+}
+
+fn compile_wat(wat: &str) -> Result<Vec<u8>, wat::Error> {
+    wat::parse_str(wat)
+}
+
+fn host_function_gas(wasm_name: &str) -> Result<u64, UnknownHostFunction> {
+    xrpl_host_functions::HostFunctionSpec::ALL
+        .iter()
+        .find(|op| op.wasm_name() == wasm_name)
+        .map(|op| op.gas())
+        .ok_or_else(|| UnknownHostFunction(wasm_name.to_owned()))
+}
+
+#[derive(Debug)]
+struct UnknownHostFunction(String);
+
+impl std::fmt::Display for UnknownHostFunction {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "no host function is imported as `{}`", self.0)
+    }
+}
+
+impl std::error::Error for UnknownHostFunction {}
+
+#[cfg(test)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use super::*;
+
+    #[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_host_function_reports_the_gas_its_declaration_gives_it() {
+        // `trace` is the cheapest declaration in the table; the point is not the number but
+        // that the lookup reaches the same constant the engine charges from.
+        assert_eq!(
+            host_function_gas("trace").expect("trace is a host function"),
+            xrpl_host_functions::HostFunctionSpec::Trace.gas()
+        );
+    }
+
+    #[test]
+    fn every_host_function_is_reachable_by_its_import_name() {
+        for op in xrpl_host_functions::HostFunctionSpec::ALL {
+            assert_eq!(
+                host_function_gas(op.wasm_name()).expect("declared"),
+                op.gas(),
+                "{} must be reachable by name",
+                op.wasm_name()
+            );
+        }
+    }
+
+    #[test]
+    fn an_unknown_name_is_an_error_rather_than_zero_gas() {
+        host_function_gas("not_a_host_function").expect_err("must not resolve");
+    }
+
+    #[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,15 @@
+[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" }
+
+[lints]
+workspace = true

crates/xrpl-wasm-vm/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+wasmi = { version = "2.0.0", default-features = false, features = ["std", "validate", "portable-dispatch"] }
+xrpl-host-functions = { path = "../xrpl-host-functions", features = ["wasmi_glue"] }
+
+[dev-dependencies]
+wat = "1"
+
+[lints]
+workspace = true

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

@@ -0,0 +1,941 @@
+use crate::args::OutBytes;
+use crate::vm::{MAX_FIELD_BYTES, VmState};
+use core::ops::Range;
+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))
+}
+
+/// The guest's memory, for a call that reads its inputs and writes nothing back.
+/// An argument read out of the slice is borrowed rather than copied.
+///
+/// A call that also writes takes both borrows at once, so [`write_buffered`] and
+/// [`write_mant_exp`] hand over the same slice themselves.
+pub(crate) fn guest_memory<'a>(caller: &'a Caller<'_, VmState<'_>>) -> CallResult<&'a [u8]> {
+    let mem = memory(caller)?;
+    Ok(mem.data(caller))
+}
+
+/// 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, the
+/// cap, nor the budget, and all three checks below are reachable.
+pub(crate) fn write_into(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: OutBytes,
+    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;
+    let budget = usize::try_from(caller.data().transfer_budget.get()).unwrap_or(usize::MAX);
+    let buf = mem
+        .data_mut(&mut *caller)
+        .get_mut(range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    let buf = &mut buf[..cap.min(MAX_FIELD_BYTES).min(budget)];
+
+    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 read any number of input
+/// arguments out of it — 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: OutBytes,
+    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;
+
+fn check_fits(data: &[u8], range: &Range<usize>, width: usize) -> HostResult<()> {
+    let region = data
+        .get(range.clone())
+        .ok_or(HostError::PointerOutOfBounds)?;
+    if region.len() < width {
+        return Err(HostError::BufferTooSmall);
+    }
+    Ok(())
+}
+
+/// 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: OutBytes,
+    exponent_out: OutBytes,
+    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());
+    }
+
+    let mant_range = mantissa_out.range()?;
+    check_fits(data, &mant_range, MANTISSA_BYTES)?;
+    let exp_range = exponent_out.range()?;
+    check_fits(data, &exp_range, EXPONENT_BYTES)?;
+
+    charge_transfer(state, MANTISSA_BYTES + EXPONENT_BYTES)?;
+
+    let mant_dst = data
+        .get_mut(mant_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    mant_dst[..MANTISSA_BYTES].copy_from_slice(&state.out_buffer[..MANTISSA_BYTES]);
+    let exp_dst = data
+        .get_mut(exp_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    exp_dst[..EXPONENT_BYTES]
+        .copy_from_slice(&state.out_buffer[MANTISSA_BYTES..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)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+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: u32, _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: u32, _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: u32,
+            _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: u32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn offer_keylet(&self, _account: &[u8], _seq: u32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn oracle_keylet(
+            &self,
+            _account: &[u8],
+            _doc_id: u32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn paychannel_keylet(
+            &self,
+            _account: &[u8],
+            _destination: &[u8],
+            _seq: u32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn permissioned_domain_keylet(
+            &self,
+            _account: &[u8],
+            _seq: u32,
+            _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: u32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn vault_keylet(&self, _account: &[u8], _seq: u32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn sponsorship_keylet(
+            &self,
+            _sponsor: &[u8],
+            _sponsee: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn loan_broker_keylet(
+            &self,
+            _owner: &[u8],
+            _seq: u32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn loan_keylet(
+            &self,
+            _loan_broker_id: &[u8],
+            _loan_seq: u32,
+            _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_type: TraceDataType, _data: &[u8]) -> 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, _out: &mut [u8], _mode: i32) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_uint(&self, _x: &[u8], _out: &mut [u8], _mode: i32) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stamount(
+            &self,
+            _amount: &[u8],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stnumber(
+            &self,
+            _number: &[u8],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_int(&self, _x: &[u8], _out: &mut [u8], _mode: i32) -> 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,
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> 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],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_subtract(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_multiply(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_divide(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_power(
+            &self,
+            _x: &[u8],
+            _n: i32,
+            _out: &mut [u8],
+            _mode: i32,
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn instance_param(
+            &self,
+            _index: i32,
+            _st_type_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn function_param(
+            &self,
+            _index: i32,
+            _st_type_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_data_object_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_data_nested_object_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _nested_key: &str,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_data_array_element_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _index: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_data_nested_array_element_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _index: i32,
+            _nested_key: &str,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn set_data_object_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _value: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn set_data_nested_object_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _nested_key: &str,
+            _value: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn set_data_array_element_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _index: i32,
+            _value: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn set_data_nested_array_element_field(
+            &self,
+            _account: &[u8],
+            _key: &str,
+            _index: i32,
+            _nested_key: &str,
+            _value: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn build_txn(&self, _tx_type: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn add_txn_field(&self, _index: i32, _field: i32, _data: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn emit_built_txn(&self, _index: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn emit_txn(&self, _txn: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn emit_event(&self, _name: &str, _data: &[u8]) -> HostResult<i32> {
+            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/args.rs

@@ -0,0 +1,244 @@
+//! A host call's arguments as they arrive: one type per declared parameter the
+//! ABI marshals, built by `register.rs`'s generated closures and read by its
+//! bodies. A wasm scalar (`i32`, `i64`) is passed through as itself and has no
+//! type here.
+//!
+//! What the types buy is that **a body cannot mistake one argument for another**:
+//! an input region offered where an output one belongs is a compile error naming
+//! both, where two loose `i32`s would let a rounding mode be read as a buffer
+//! length. A derived signature cannot catch that, every one of these being
+//! `i32, i32` on the wire.
+//!
+//! The arguments arrive unchecked and are judged where they are read — `InU32`'s
+//! region must hold exactly four bytes, `InStr`'s must be UTF-8, a [`TraceCode`]
+//! must name a rendering — so they are refused in the order the body reads them.
+//!
+//! **The `from_wasm` impls below are half of `wasmi_glue!`'s contract** and the
+//! only construction these types have; `register.rs`'s `glue_env` is where the
+//! macro is told which type marshals which declared one. Which of the two traits
+//! a type takes is the ABI's decision, so `InU32` is a region rather than the
+//! scalar its declared `u32` reads like.
+
+use crate::vm::MAX_FIELD_BYTES;
+use core::ops::Range;
+use xrpl_host_functions::{FromWasmRegion, FromWasmScalar, HostError, HostResult, TraceDataType};
+
+/// A byte region as the guest declared it: the `(ptr, len)` pair off the wire, not
+/// yet checked.
+///
+/// The shared half of the four region types below, which differ in what reading
+/// one means. The fields being out of reach makes [`range`](Region::range) the
+/// only way to indices, so the check can be deferred but not skipped — and
+/// construction is infallible so that a malformed region is refused in the order
+/// the call's own helper chooses.
+#[derive(Copy, Clone)]
+struct Region {
+    ptr: i32,
+    len: i32,
+}
+
+impl Region {
+    fn new(ptr: i32, len: i32) -> Region {
+        Region { ptr, len }
+    }
+
+    /// `start..end` as indices. The conversion is the negativity check, and the
+    /// checked addition guards a 32-bit `usize`, where two `i32`s can sum past the
+    /// end.
+    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. The slice aliases `data`.
+    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)
+    }
+}
+
+/// A declared `&[u8]`: an input region the host borrows.
+#[derive(Copy, Clone)]
+pub(crate) struct InBytes(Region);
+
+impl FromWasmRegion for InBytes {
+    fn from_wasm(ptr: i32, len: i32) -> InBytes {
+        InBytes(Region::new(ptr, len))
+    }
+}
+
+impl InBytes {
+    /// The region's bytes, aliasing the guest's memory rather than copied out of it.
+    pub(crate) fn read(self, data: &[u8]) -> HostResult<&[u8]> {
+        self.0.read(data)
+    }
+}
+
+/// A declared `&str`: an input region whose bytes are text.
+#[derive(Copy, Clone)]
+pub(crate) struct InStr(Region);
+
+impl FromWasmRegion for InStr {
+    fn from_wasm(ptr: i32, len: i32) -> InStr {
+        InStr(Region::new(ptr, len))
+    }
+}
+
+impl InStr {
+    /// The region's bytes as text. The read is also the UTF-8 check, so a host is
+    /// never the one to validate them.
+    pub(crate) fn read(self, data: &[u8]) -> HostResult<&str> {
+        core::str::from_utf8(self.0.read(data)?).map_err(|_| HostError::InvalidParams)
+    }
+}
+
+/// A declared `u32`: an input region holding the number as four little-endian
+/// bytes, which is how the guest SDK passes a sequence number.
+#[derive(Copy, Clone)]
+pub(crate) struct InU32(Region);
+
+impl FromWasmRegion for InU32 {
+    fn from_wasm(ptr: i32, len: i32) -> InU32 {
+        InU32(Region::new(ptr, len))
+    }
+}
+
+impl InU32 {
+    /// The number the region holds. The width is the ABI's, so any length but four
+    /// is `InvalidParams`.
+    pub(crate) fn read(self, data: &[u8]) -> HostResult<u32> {
+        let bytes: [u8; 4] = self
+            .0
+            .read(data)?
+            .try_into()
+            .map_err(|_| HostError::InvalidParams)?;
+        Ok(u32::from_le_bytes(bytes))
+    }
+}
+
+/// A declared `&mut [u8]`: the region the host's answer is written to.
+///
+/// It has no `read`: what a call may put here is decided by the `abi.rs` helper
+/// serving it, against the value's length and the run's budget, and the host is
+/// never handed the guest's capacity.
+#[derive(Copy, Clone)]
+pub(crate) struct OutBytes(Region);
+
+impl FromWasmRegion for OutBytes {
+    fn from_wasm(ptr: i32, len: i32) -> OutBytes {
+        OutBytes(Region::new(ptr, len))
+    }
+}
+
+impl OutBytes {
+    pub(crate) fn range(self) -> HostResult<Range<usize>> {
+        self.0.range()
+    }
+}
+
+/// A declared `TraceDataType`: the `i32` code naming how `trace` is to render its
+/// data. The one marshalled argument that is not a region, so reading it needs no
+/// guest memory.
+#[derive(Copy, Clone)]
+pub(crate) struct TraceCode(i32);
+
+impl FromWasmScalar for TraceCode {
+    fn from_wasm(code: i32) -> TraceCode {
+        TraceCode(code)
+    }
+}
+
+impl TraceCode {
+    /// The type the code names, or `InvalidParams`: a rendering the guest did not
+    /// ask for is not one to guess at.
+    pub(crate) fn read(self) -> HostResult<TraceDataType> {
+        TraceDataType::from_code(self.0).ok_or(HostError::InvalidParams)
+    }
+}
+
+#[cfg(test)]
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod tests {
+    use super::*;
+
+    /// The guest memory these tests read out of: sixteen bytes at index 0.
+    const MEMORY: [u8; 16] = [
+        0x78, 0x56, 0x34, 0x12, b'h', b'i', 0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+    ];
+
+    #[test]
+    fn a_u32_argument_is_four_little_endian_bytes() {
+        assert_eq!(InU32::from_wasm(0, 4).read(&MEMORY), Ok(0x1234_5678));
+    }
+
+    /// A longer region is refused too, rather than its first four bytes read as
+    /// the answer.
+    #[test]
+    fn a_u32_argument_of_any_other_width_is_refused() {
+        for len in [0, 1, 3, 5, 8] {
+            assert_eq!(
+                InU32::from_wasm(0, len).read(&MEMORY),
+                Err(HostError::InvalidParams),
+                "{len} bytes"
+            );
+        }
+    }
+
+    /// The read is the UTF-8 check, so a host implementing `trace` has nothing
+    /// left to validate.
+    #[test]
+    fn a_str_argument_is_checked_where_it_is_read() {
+        assert_eq!(InStr::from_wasm(4, 2).read(&MEMORY), Ok("hi"));
+        assert_eq!(
+            InStr::from_wasm(6, 1).read(&MEMORY),
+            Err(HostError::InvalidParams),
+            "0xff is not UTF-8"
+        );
+    }
+
+    /// A region past the end of guest memory is refused rather than clamped, and
+    /// one past the field cap is refused before the memory is consulted at all.
+    #[test]
+    fn a_region_is_held_to_the_memory_and_to_the_field_cap() {
+        assert_eq!(
+            InBytes::from_wasm(8, 16).read(&MEMORY),
+            Err(HostError::PointerOutOfBounds)
+        );
+
+        let past_the_cap = i32::try_from(MAX_FIELD_BYTES).expect("the cap is a small constant") + 1;
+        assert_eq!(
+            InBytes::from_wasm(0, past_the_cap).read(&MEMORY),
+            Err(HostError::DataFieldTooLarge)
+        );
+
+        assert_eq!(
+            InBytes::from_wasm(-1, 4).read(&MEMORY),
+            Err(HostError::InvalidParams)
+        );
+    }
+
+    /// Every code the ABI has, and nothing else: an unknown one is refused rather
+    /// than rendered some other way.
+    #[test]
+    fn a_trace_code_names_a_rendering_or_none() {
+        for &data_type in TraceDataType::ALL {
+            assert_eq!(TraceCode::from_wasm(data_type.code()).read(), Ok(data_type));
+        }
+
+        for code in [0, -1, i32::MAX] {
+            assert_eq!(
+                TraceCode::from_wasm(code).read(),
+                Err(HostError::InvalidParams),
+                "{code}"
+            );
+        }
+    }
+}