feat: Remove float_root

Co-authored-by: TimothyBanks <tbanks@ripple.com>

.cspell.config.yaml

@@ -7,6 +7,7 @@ ignorePaths:
   - cmake/**
   - LICENSE.md
   - .clang-tidy
+  - src/test/app/wasm_fixtures/*.c
   - nix/check-tools/*.txt # generated, and full of Nix store hashes
 language: en
 allowCompoundWords: true # TODO (#6334)
@@ -68,6 +69,7 @@ words:
   - Btrfs
   - Buildx
   - canonicality
+  - cdylib
   - canonicalised
   - cctools
   - changespq
@@ -105,6 +107,7 @@ words:
   - deleteme
   - demultiplexer
   - deserializaton
+  - desugars
   - desync
   - desynced
   - determ
@@ -131,6 +134,7 @@ words:
   - gcov
   - gcovr
   - ghead
+  - gmock
   - Gnutella
   - godexsoft
   - gpgcheck
@@ -140,7 +144,9 @@ words:
   - hwaddress
   - hwrap
   - ifndef
+  - impls
   - inequation
+  - initialiser
   - insuf
   - insuff
   - invasively
@@ -250,6 +256,7 @@ words:
   - pyparsing
   - qalloc
   - qbsprofile
+  - qself
   - queuable
   - Raphson
   - rcflags
@@ -307,6 +314,7 @@ words:
   - STATSDCOLLECTOR
   - stissue
   - stnum
+  - stnumber
   - stobj
   - stobject
   - stpath
@@ -347,6 +355,7 @@ words:
   - unflatten
   - unfund
   - unimpair
+  - unmetered
   - unroutable
   - unscalable
   - unserviced
@@ -367,6 +376,8 @@ words:
   - vfalco
   - vinnie
   - wasmi
+  - wasmparser
+  - Werror
   - wextra
   - wptr
   - writeme
@@ -375,6 +386,7 @@ words:
   - xbridge
   - xchain
   - xcrun
+  - xfloat
   - ximinez
   - XMACRO
   - xored

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

@@ -20,10 +20,9 @@ inputs:
     required: false
     default: ""
   save-if:
-    description: >
-      Condition for saving the cache after the job. Defaults to save only from develop branch
+    description: "Condition for saving the cache after the job."
     required: false
-    default: ${{ github.ref == 'refs/heads/develop' }}
+    default: "true"
 
 runs:
   using: composite

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

@@ -12,7 +12,6 @@ _BASE_CMAKE_ARGS = [
     "-Dwerr=ON",
     "-Dxrpld=ON",
     "-Dwextra=ON",
-    "-Drust=ON",
 ]
 
 # Maps sanitizer names (as used in cmake) to short config-name suffixes.

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

@@ -167,6 +167,7 @@ jobs:
         with:
           cache-directories: ${{ env.BUILD_DIR }}/corrosion
           key: ${{ inputs.config_name }}
+          save-if: ${{ github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/release') }}
           # two workspaces here because build artifacts are located in 2 places:
           # - crates/target when cargo is called directly
           # - build/cargo when cargo is called by cmake
@@ -372,7 +373,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

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

@@ -63,6 +63,7 @@ jobs:
         uses: ./.github/actions/cargo-cache
         with:
           cache-directories: ${{ env.BUILD_DIR }}/corrosion
+          save-if: ${{ github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/release') }}
           workspaces: crates -> ../${{ env.BUILD_DIR }}/cargo
 
       - name: Setup Conan
@@ -86,7 +87,6 @@ jobs:
               -Dwerr=ON \
               -Dxrpld=ON \
               -Dverify_headers=ON \
-              -Drust=ON \
               ..
 
       - name: Build clang-tidy prerequisites

API-CHANGELOG.md

@@ -54,9 +54,6 @@ This section contains changes targeting a future version.
 - `submit`: The `fail_hard` field now returns an error if the value is not a boolean. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 - `subscribe`: The `taker` field in the `books` array now returns `actMalformed` instead of `badIssuer` if the value is not a valid account. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 - Fixed a bug in `Forwarded` HTTP header parsing where the extracted IP address could be incorrect when no comma or semicolon delimiter follows the address. This could cause the server to misidentify a client's IP address when operating behind a reverse proxy. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `vault_info`: Errors now identify what the request got wrong instead of reporting every failure as the unregistered token `malformedRequest`, and the `error`, `error_code` and `error_message` fields now agree with each other. An invalid `vault_id` or `seq` returns `invalidParams`, an invalid `owner` returns `actMalformed`, and a request that mixes `vault_id` with `owner`/`seq` or supplies neither returns `invalidParams` with a message naming the accepted combinations. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: A well-formed all-zero `vault_id` now returns `entryNotFound` instead of being rejected as malformed, and `entryNotFound` responses now include `error_code` and `error_message`. Clients that request `ripplerpc` 3.0 or above therefore receive HTTP 400 with that error rather than HTTP 200. [#8015](https://github.com/XRPLF/rippled/pull/8015)
-- `vault_info`: `vault_id` and `owner` must now be strings, matching how `ledger_entry` reads the same fields. An object or an array in either field previously produced an internal error, and a number was silently converted to its decimal text; `vault_id` now returns `invalidParams` and `owner` returns `actMalformed`. [#8015](https://github.com/XRPLF/rippled/pull/8015)
 - `gateway_balances`: The `account` and `ident` fields now return an `invalidParams` error if the value is not a string, instead of an `internal` error. [#7655](https://github.com/XRPLF/rippled/pull/7655)
 - `account_lines`: The `peer` field now returns an error if the value is not a string. [#7728](https://github.com/XRPLF/rippled/pull/7728)
 

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
 
@@ -304,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. |
@@ -319,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

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

CONTRIBUTING.md

@@ -321,7 +321,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

cmake/XrplCore.cmake

@@ -207,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(

cmake/XrplSettings.cmake

@@ -32,11 +32,6 @@ endif()
 
 option(benchmark "Build benchmarks" ON)
 
-# When OFF, the crates directory is not added to the build at all: no Rust
-# toolchain is required, no cxxbridge bindings are generated, and the C++ tests
-# that consume those bindings are left out of the build tree.
-option(rust "Build the Rust crates and the C++ code that depends on them" OFF)
-
 # Enabled by default so every header is compiled on its own as the main file of
 # its own compile_commands.json entry - this is what lets clang-tidy (and clangd
 # and IDEs) analyse a header's own includes directly. The per-header objects are

cmake/scripts/codegen/generate_tx_classes.py

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

conanfile.py

@@ -152,8 +152,12 @@ class Xrpl(ConanFile):
         "CMakeLists.txt",
         "cfg/*",
         "cmake/*",
+        "crates/*",
+        "crates/.cargo/*",
+        "!crates/target/*",
         "external/*",
         "include/*",
+        "rust-toolchain.toml",
         "src/*",
     )
 

crates/CMakeLists.txt

@@ -101,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"
@@ -66,7 +78,7 @@ dependencies = [
  "cxxbridge-cmd",
  "cxxbridge-flags",
  "cxxbridge-macro",
- "foldhash",
+ "foldhash 0.2.0",
  "link-cplusplus",
 ]
 
@@ -129,12 +141,27 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.0"
@@ -148,9 +175,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown",
+ "hashbrown 0.17.0",
 ]
 
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "link-cplusplus"
 version = "1.0.12"
@@ -160,6 +199,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -178,19 +223,18 @@ dependencies = [
  "proc-macro2",
 ]
 
-[[package]]
-name = "rs-hello_world"
-version = "0.1.0"
-dependencies = [
- "cxx",
-]
-
 [[package]]
 name = "scratch"
 version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d68f2ec51b097e4c1a75b681a8bec621909b5e91f15bb7b840c4f2f7b01148b2"
 
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -227,6 +271,22 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "spin"
+version = "0.9.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
+
+[[package]]
+name = "string-interner"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"
+dependencies = [
+ "hashbrown 0.15.5",
+ "serde",
+]
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -276,6 +336,99 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 
+[[package]]
+name = "wasm-encoder"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09480d646178e5fdd12bb06e812d0af9a3a191dbc9cd697fdc86687beade7393"
+dependencies = [
+ "leb128fmt",
+ "wasmparser 0.254.0",
+]
+
+[[package]]
+name = "wasmi"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2300d0f78cba12f14e29e8dd157ea64050c0a688179aefdb2050105805594a0c"
+dependencies = [
+ "spin",
+ "wasmi_collections",
+ "wasmi_core",
+ "wasmi_ir",
+ "wasmparser 0.239.0",
+]
+
+[[package]]
+name = "wasmi_collections"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8a8c42a2a76148d43097b1d7cc2a5bf33d5c23bd4dd69015fc887e311767884"
+dependencies = [
+ "string-interner",
+]
+
+[[package]]
+name = "wasmi_core"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9013136083d988725953390bf668b64b7a218fabf26f8b913bbc59546b97ee27"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "wasmi_ir"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba1fa003f79156f406d62ef0e1464dc03e11ace37170e9fa7524299a75ad8f68"
+dependencies = [
+ "wasmi_core",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.239.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c9d90bb93e764f6beabf1d02028c70a2156a6583e63ac4218dd07ef733368b0"
+dependencies = [
+ "bitflags",
+ "indexmap",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5769a29f799fbab136aaf65b4fe5384cd7d93fe6fc9ba0dcb6c8382a1f16e27"
+dependencies = [
+ "bitflags",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "wast"
+version = "254.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7ed4dfc8f6b9fc38b231065e2cdfbf7359af5ab945990abf09658dcc63c3e32"
+dependencies = [
+ "bumpalo",
+ "leb128fmt",
+ "memchr",
+ "unicode-width",
+ "wasm-encoder",
+]
+
+[[package]]
+name = "wat"
+version = "1.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7127f7f9b8f127c879991cecd35f494e4628bae1b0874c681414d8d8831e952c"
+dependencies = [
+ "wast",
+]
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -299,3 +452,46 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
  "windows-link",
 ]
+
+[[package]]
+name = "xrpl-host-functions"
+version = "0.1.0"
+dependencies = [
+ "xrpl-host-functions-macros",
+]
+
+[[package]]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-testkit"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "wat",
+]
+
+[[package]]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+dependencies = [
+ "wasmi",
+ "wat",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-vm-ffi"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "xrpl-host-functions",
+ "xrpl-wasm-vm",
+]

crates/Cargo.toml

@@ -1,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/hello_world/src/lib.rs

@@ -1,10 +0,0 @@
-#[cxx::bridge(namespace = "rs::hello_world")]
-mod ffi {
-    extern "Rust" {
-        fn hello_world() -> String;
-    }
-}
-
-pub fn hello_world() -> String {
-    "hello_world".to_string()
-}

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

@@ -0,0 +1,18 @@
+[package]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+syn = { version = "3", features = ["full"] }
+quote = "1"
+proc-macro2 = "1"
+
+# The 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"

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

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

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

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

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

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

crates/xrpl-host-functions/Cargo.toml

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

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

@@ -0,0 +1,503 @@
+//! The wasm host ABI: the one place it is declared.
+//!
+//! `host_functions!` turns the declaration block at the bottom of this file into the
+//! [`HostFunctions`] trait a host implements and the [`HostFunctionSpec`] table a
+//! wasm engine registers from.
+//!
+//! The split: hand-written here is the vocabulary the declarations are written in —
+//! [`HostError`], [`TraceDataType`], [`HostResult`], [`HASH_LEN`] — and everything
+//! derived from the declarations is generated. The expansion names nothing this file
+//! does not, so the two sides meet only in the block below.
+//!
+//! So this file is lists — error codes, trace data types, functions. The `macro_rules!`
+//! that expand the first two into enums live in `macros.rs`.
+
+#![no_std]
+
+#[macro_use]
+mod macros;
+
+// Not re-exported: the ABI is declared once, here, and this is the only call site.
+use xrpl_host_functions_macros::host_functions;
+
+host_errors! {
+    Unimplemented = -1,
+    FieldNotFound = -2,
+    BufferTooSmall = -3,
+    NoArray = -4,
+    NotLeafField = -5,
+    LocatorMalformed = -6,
+    SlotOutRange = -7,
+    SlotsFull = -8,
+    EmptySlot = -9,
+    LedgerObjNotFound = -10,
+    OutOfTransferLimit = -11,
+    DataFieldTooLarge = -12,
+    PointerOutOfBounds = -13,
+    NoMemExported = -14,
+    InvalidParams = -15,
+    InvalidAccount = -16,
+    InvalidField = -17,
+    IndexOutOfBounds = -18,
+    FloatInputMalformed = -19,
+    FloatComputationError = -20,
+    /// Internal fatal error.
+    /// User code will never see this error but keep it reserved to not rely on the value.
+    InternalFatal = -2147483648,
+}
+
+/// Convenience alias for the trait's fallible returns.
+pub type HostResult<T> = Result<T, HostError>;
+
+/// A `sha512Half` digest: the first 32 bytes of a SHA-512, as XRPL uses it.
+pub const HASH_LEN: usize = 32;
+
+trace_data_types! {
+    /// 8 little-endian bytes, rendered as a signed decimal.
+    Int64 = 1,
+    /// 8 little-endian bytes, rendered as an unsigned decimal.
+    Uint64 = 2,
+    /// A serialized XRPL float: 12 bytes, mantissa then exponent.
+    Xfloat = 3,
+    /// A 20-byte account ID, rendered as base58.
+    Account = 4,
+    /// A serialized `STAmount`.
+    Amount = 5,
+    /// Raw bytes, hex-encoded.
+    AsHex = 6,
+    /// Bytes rendered verbatim as text.
+    AsText = 7,
+}
+
+host_functions! {
+    /// The sequence number of the ledger being built, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "ldgr_index"]
+    fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The close time of the parent (last-closed) ledger, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_time"]
+    fn get_parent_ledger_time(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The hash of the parent (last-closed) ledger, as 32 bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_hash"]
+    fn get_parent_ledger_hash(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The base fee of the ledger being built, in drops, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "base_fee"]
+    fn get_base_fee(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// Whether an amendment is enabled. The input is either its 32-byte id or its name;
+    /// the answer is `1` if enabled and `0` if not.
+    #[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. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    #[gas = 350]
+    #[wasm_name = "check_id"]
+    fn check_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Credential`, computed from the 20-byte subject and
+    /// issuer account ids and a credential-type byte string.
+    #[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. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern.
+    #[gas = 350]
+    #[wasm_name = "escrow_id"]
+    fn escrow_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `RippleState` (trust line), computed from two 20-byte
+    /// account ids and a 20-byte currency.
+    #[gas = 400]
+    #[wasm_name = "trustline_id"]
+    fn trust_line_keylet(
+        &self,
+        account1: &[u8],
+        account2: &[u8],
+        currency: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPTokenIssuance`, computed from the 20-byte issuer
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its `i32`
+    /// bit pattern.
+    #[gas = 350]
+    #[wasm_name = "mpt_issuance_id"]
+    fn mptoken_issuance_keylet(
+        &self,
+        issuer: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPToken`, computed from a 24-byte MPT issuance id and
+    /// the 20-byte holder account.
+    #[gas = 500]
+    #[wasm_name = "mptoken_id"]
+    fn mptoken_keylet(&self, mptid: &[u8], holder: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `NFTokenOffer`, computed from the 20-byte owner account
+    /// and its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern.
+    #[gas = 350]
+    #[wasm_name = "nft_offer_id"]
+    fn nftoken_offer_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Offer`, computed from the 20-byte owner account and
+    /// its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern.
+    #[gas = 350]
+    #[wasm_name = "offer_id"]
+    fn offer_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Oracle`, computed from the 20-byte owner account and
+    /// its document id. `doc_id` is the guest's `u32` carried as its `i32` bit pattern.
+    #[gas = 350]
+    #[wasm_name = "oracle_id"]
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PayChannel`, computed from the 20-byte source account,
+    /// the 20-byte destination account, and the channel's sequence number. `seq` is the
+    /// guest's `u32` carried as its `i32` bit pattern.
+    #[gas = 350]
+    #[wasm_name = "paychan_id"]
+    fn paychannel_keylet(
+        &self,
+        account: &[u8],
+        destination: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PermissionedDomain`, computed from the 20-byte owner
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its `i32`
+    /// bit pattern.
+    #[gas = 350]
+    #[wasm_name = "permissioned_domain_id"]
+    fn permissioned_domain_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `SignerList`, computed from its 20-byte owner account.
+    #[gas = 350]
+    #[wasm_name = "signers_id"]
+    fn signer_list_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Ticket`, computed from the 20-byte owner account and
+    /// its ticket sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern.
+    #[gas = 350]
+    #[wasm_name = "ticket_id"]
+    fn ticket_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Vault`, computed from the 20-byte owner account and its
+    /// sequence number. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    #[gas = 350]
+    #[wasm_name = "vault_id"]
+    fn vault_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The XRPL `sha512Half` of `data`: the first [`HASH_LEN`] bytes of its SHA-512.
+    #[gas = 2000]
+    #[wasm_name = "sha512_half"]
+    fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// Writes `msg` to the trace log, followed by `data` rendered as `data_type` says.
+    ///
+    /// The one declaration whose wasm function has **no result**: this node's own log
+    /// is its only effect, so a guest is told nothing. An `Err` from a host therefore
+    /// reaches it in no form, and only the host-fatal ones do anything at all.
+    ///
+    /// It is also the one declaration that is **not** the wasm parameter order.
+    /// `data_type` is the third wasm parameter, between the two regions, because that
+    /// is where the guest stdlib declares it; `register.rs` takes the arguments in wasm
+    /// order and calls this in declaration order.
+    #[gas = 30]
+    #[wasm_name = "trace"]
+    fn trace(&self, msg: &str, data: &[u8], data_type: TraceDataType) -> HostResult<()>;
+
+    /// Stores `data` as the current object's data field, replacing whatever was there,
+    /// and returns the number of bytes stored; `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, mode: i32, out: &mut [u8]) -> 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], mode: i32, out: &mut [u8]) -> 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], mode: i32, out: &mut [u8]) -> 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], mode: i32, out: &mut [u8]) -> 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], mode: i32, out: &mut [u8]) -> 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,
+        mode: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// Compares floats `x` and `y`, returning a negative, zero, or positive scalar as
+    /// `x` is less than, equal to, or greater than `y`.
+    #[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], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float difference `x - y` under rounding `mode`.
+    #[gas = 160]
+    #[wasm_name = "float_sub"]
+    fn float_subtract(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float product `x * y` under rounding `mode`.
+    #[gas = 300]
+    #[wasm_name = "float_mult"]
+    fn float_multiply(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float quotient `x / y` under rounding `mode`.
+    #[gas = 300]
+    #[wasm_name = "float_div"]
+    fn float_divide(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> 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, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+}

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

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

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

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

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

@@ -0,0 +1,996 @@
+//! Exercises the API that `host_functions!` generates, not the macro itself:
+//! the `HostFunctions` trait is implementable and callable both directly and
+//! through `&dyn`, and the generated `HostFunctionSpec` and `TraceDataType`
+//! tables agree with the declarations in `src/lib.rs`. The macro's own parsing
+//! and diagnostics are covered by the unit tests in `xrpl-host-functions-macros`.
+
+use std::cell::RefCell;
+use std::collections::HashSet;
+
+use xrpl_host_functions::{
+    HASH_LEN, HostError, HostFunctionSpec, HostFunctions, HostResult, TraceDataType,
+};
+
+/// Records what it was asked to do; enough to prove the trait is usable.
+///
+/// Every method takes `&self`, so a host that records anything keeps it behind
+/// interior mutability.
+#[derive(Default)]
+struct FakeHost {
+    traced: RefCell<Vec<String>>,
+}
+
+/// The contract every byte-producing host function follows: write only if the
+/// value fits, and report its true length either way, so the engine can turn a
+/// value that doesn't fit into `BufferTooSmall` without the host knowing the
+/// guest's buffer size.
+fn put(out: &mut [u8], value: &[u8]) -> HostResult<usize> {
+    if let Some(dst) = out.get_mut(..value.len()) {
+        dst.copy_from_slice(value);
+    }
+    Ok(value.len())
+}
+
+impl HostFunctions for FakeHost {
+    fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize> {
+        put(out, &7u32.to_le_bytes())
+    }
+
+    fn get_parent_ledger_time(&self, out: &mut [u8]) -> HostResult<usize> {
+        put(out, &9u32.to_le_bytes())
+    }
+
+    fn get_parent_ledger_hash(&self, out: &mut [u8]) -> HostResult<usize> {
+        put(out, &[0xab; HASH_LEN])
+    }
+
+    fn get_base_fee(&self, out: &mut [u8]) -> HostResult<usize> {
+        put(out, &10u32.to_le_bytes())
+    }
+
+    /// Returns a flag rather than bytes, and reads its input: enabled unless empty.
+    fn is_amendment_enabled(&self, amendment: &[u8]) -> HostResult<i32> {
+        Ok(i32::from(!amendment.is_empty()))
+    }
+
+    /// Returns a slot: the requested one, or slot 1 when asked to pick.
+    fn cache_ledger_obj(&self, _obj_id: &[u8], cache_idx: i32) -> HostResult<i32> {
+        Ok(if cache_idx == 0 { 1 } else { cache_idx })
+    }
+
+    /// A field getter over the transaction; fails on a negative selector.
+    fn get_tx_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize> {
+        if field < 0 {
+            return Err(HostError::FieldNotFound);
+        }
+        put(out, &[field as u8])
+    }
+
+    /// Fails on a field it doesn't know, so the error channel is exercised too.
+    fn get_current_ledger_obj_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize> {
+        if field < 0 {
+            return Err(HostError::FieldNotFound);
+        }
+        put(out, &[field as u8])
+    }
+
+    /// A field getter over a cached object, keyed by slot and selector.
+    fn get_ledger_obj_field(
+        &self,
+        cache_idx: i32,
+        field: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if cache_idx <= 0 || field < 0 {
+            return Err(HostError::FieldNotFound);
+        }
+        put(out, &[cache_idx as u8, field as u8])
+    }
+
+    /// A nested-field getter over the transaction, keyed by the locator bytes.
+    fn get_tx_nested_field(&self, locator: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        put(out, &[locator[0], locator.len() as u8])
+    }
+
+    /// The same, over the current ledger object.
+    fn get_current_ledger_obj_nested_field(
+        &self,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        put(out, &[locator.len() as u8, locator[0]])
+    }
+
+    /// The same, over a cached object keyed by slot.
+    fn get_ledger_obj_nested_field(
+        &self,
+        cache_idx: i32,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if cache_idx <= 0 || locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        put(out, &[cache_idx as u8, locator[0]])
+    }
+
+    /// A scalar-in, scalar-out count; `NoArray` on a negative selector.
+    fn get_tx_array_len(&self, field: i32) -> HostResult<i32> {
+        if field < 0 {
+            return Err(HostError::NoArray);
+        }
+        Ok(field)
+    }
+
+    /// The same, over the current ledger object.
+    fn get_current_ledger_obj_array_len(&self, field: i32) -> HostResult<i32> {
+        if field < 0 {
+            return Err(HostError::NoArray);
+        }
+        Ok(field + 1)
+    }
+
+    /// The same, over a cached object keyed by slot.
+    fn get_ledger_obj_array_len(&self, cache_idx: i32, field: i32) -> HostResult<i32> {
+        if cache_idx <= 0 || field < 0 {
+            return Err(HostError::NoArray);
+        }
+        Ok(cache_idx + field)
+    }
+
+    /// A nested array-length getter, keyed by the locator bytes.
+    fn get_tx_nested_array_len(&self, locator: &[u8]) -> HostResult<i32> {
+        if locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        Ok(locator.len() as i32)
+    }
+
+    /// The same, over the current ledger object.
+    fn get_current_ledger_obj_nested_array_len(&self, locator: &[u8]) -> HostResult<i32> {
+        if locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        Ok(locator.len() as i32 + 1)
+    }
+
+    /// The same, over a cached object keyed by slot.
+    fn get_ledger_obj_nested_array_len(&self, cache_idx: i32, locator: &[u8]) -> HostResult<i32> {
+        if cache_idx <= 0 || locator.is_empty() {
+            return Err(HostError::LocatorMalformed);
+        }
+        Ok(cache_idx + locator.len() as i32)
+    }
+
+    /// Reads three regions and returns a verdict: valid unless the signature is empty.
+    fn check_signature(
+        &self,
+        _message: &[u8],
+        signature: &[u8],
+        _pubkey: &[u8],
+    ) -> HostResult<i32> {
+        Ok(i32::from(!signature.is_empty()))
+    }
+
+    /// A keylet getter: reads an account, writes a 32-byte keylet; `InvalidAccount`
+    /// on an empty account.
+    fn account_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// A two-asset keylet getter; `InvalidParams` if the two assets are equal.
+    fn amm_keylet(&self, asset1: &[u8], asset2: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if asset1 == asset2 {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[asset1.len() as u8; HASH_LEN])
+    }
+
+    /// A keylet from an account and a sequence; `InvalidAccount` on an empty account.
+    fn check_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// A keylet from subject, issuer, and credential type; `InvalidAccount` if either
+    /// account is empty, `InvalidParams` if the type is empty.
+    fn credential_keylet(
+        &self,
+        subject: &[u8],
+        issuer: &[u8],
+        credential_type: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if subject.is_empty() || issuer.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        if credential_type.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[subject[0]; HASH_LEN])
+    }
+
+    /// A keylet from two accounts; `InvalidAccount` if either is empty, `InvalidParams`
+    /// if they are equal.
+    fn delegate_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if account.is_empty() || authorize.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        if account == authorize {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same two-account shape, for a `DepositPreauth`.
+    fn deposit_preauth_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if account.is_empty() || authorize.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        if account == authorize {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[authorize[0]; HASH_LEN])
+    }
+
+    /// A single-account keylet, for a `DID`.
+    fn did_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The account-and-sequence shape, for an `Escrow`.
+    fn escrow_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// A keylet from two accounts and a currency; `InvalidAccount` if either account
+    /// is empty, `InvalidParams` if they are equal or the currency is empty.
+    fn trust_line_keylet(
+        &self,
+        account1: &[u8],
+        account2: &[u8],
+        currency: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if account1.is_empty() || account2.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        if account1 == account2 || currency.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[account1[0]; HASH_LEN])
+    }
+
+    /// The issuer-and-sequence shape, for an `MPTokenIssuance`.
+    fn mptoken_issuance_keylet(
+        &self,
+        issuer: &[u8],
+        _seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if issuer.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[issuer[0]; HASH_LEN])
+    }
+
+    /// A keylet from an MPT id and a holder; `InvalidParams` if the id is empty,
+    /// `InvalidAccount` if the holder is empty.
+    fn mptoken_keylet(&self, mptid: &[u8], holder: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if mptid.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        if holder.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[mptid[0]; HASH_LEN])
+    }
+
+    /// The account-and-sequence shape, for an `NFTokenOffer`.
+    fn nftoken_offer_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same account-and-sequence shape, for an `Offer`.
+    fn offer_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same account-and-scalar shape, for an `Oracle` keyed by document id.
+    fn oracle_keylet(&self, account: &[u8], _doc_id: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// A two-account-and-sequence shape, for a `PayChannel`; `InvalidAccount` if
+    /// either account is empty.
+    fn paychannel_keylet(
+        &self,
+        account: &[u8],
+        destination: &[u8],
+        _seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if account.is_empty() || destination.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same account-and-sequence shape, for a `PermissionedDomain`.
+    fn permissioned_domain_keylet(
+        &self,
+        account: &[u8],
+        _seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The account-only shape, for a `SignerList`.
+    fn signer_list_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same account-and-sequence shape, for a `Ticket`.
+    fn ticket_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// The same account-and-sequence shape, for a `Vault`.
+    fn vault_keylet(&self, account: &[u8], _seq: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        let mut digest = [0; HASH_LEN];
+        digest[0] = data.len() as u8;
+        put(out, &digest)
+    }
+
+    fn trace(&self, msg: &str, data: &[u8], data_type: TraceDataType) -> HostResult<()> {
+        self.traced
+            .borrow_mut()
+            .push(format!("{msg}/{data_type:?}/{}", data.len()));
+        Ok(())
+    }
+
+    /// Reads a data blob and returns the count of bytes stored.
+    fn update_data(&self, data: &[u8]) -> HostResult<i32> {
+        Ok(data.len() as i32)
+    }
+
+    /// Reads an account and an nft id, writes a byte value; `InvalidParams` if either
+    /// is empty.
+    fn get_nft(&self, account: &[u8], nft_id: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() || nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
+    /// Reads an nft id, writes a byte value; `InvalidParams` on an empty id.
+    fn get_nft_issuer(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[nft_id[0]; HASH_LEN])
+    }
+
+    /// The same, for the taxon.
+    fn get_nft_taxon(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &nft_id[0].to_le_bytes())
+    }
+
+    /// Reads an nft id and returns a scalar; `InvalidParams` on an empty id.
+    fn get_nft_flags(&self, nft_id: &[u8]) -> HostResult<i32> {
+        if nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        Ok(i32::from(nft_id[0]))
+    }
+
+    /// The same, for the transfer fee.
+    fn get_nft_transfer_fee(&self, nft_id: &[u8]) -> HostResult<i32> {
+        if nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        Ok(i32::from(nft_id[0]))
+    }
+
+    /// The same byte-output shape, for the sequence number.
+    fn get_nft_sequence(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize> {
+        if nft_id.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &nft_id[0].to_le_bytes())
+    }
+
+    /// A scalar-in float: writes the low byte of `x` as a stand-in float.
+    fn float_from_int(&self, x: i64, _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        put(out, &[x as u8])
+    }
+
+    /// A byte-in float; `InvalidParams` on an empty region.
+    fn float_from_uint(&self, x: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// The same, for a serialized amount.
+    fn float_from_stamount(&self, amount: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if amount.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[amount[0]])
+    }
+
+    /// The same, for a serialized number.
+    fn float_from_stnumber(&self, number: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if number.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[number[0]])
+    }
+
+    /// A float rounded to an integer, written as bytes.
+    fn float_to_int(&self, x: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// Writes a mantissa (its first byte) and an exponent (its first byte) to two
+    /// regions, returning their combined length.
+    fn float_to_mant_exp(
+        &self,
+        x: &[u8],
+        mantissa_out: &mut [u8],
+        exponent_out: &mut [u8],
+    ) -> HostResult<usize> {
+        if x.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        let m = put(mantissa_out, &[x[0]])?;
+        let e = put(exponent_out, &[x[0]])?;
+        Ok(m + e)
+    }
+
+    /// A two-scalar-in float.
+    fn float_from_mant_exp(
+        &self,
+        mantissa: i64,
+        _exponent: i32,
+        _mode: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize> {
+        put(out, &[mantissa as u8])
+    }
+
+    /// Reads two floats and returns a scalar; `InvalidParams` if either is empty.
+    fn float_compare(&self, x: &[u8], y: &[u8]) -> HostResult<i32> {
+        if x.is_empty() || y.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        Ok(i32::from(x[0]) - i32::from(y[0]))
+    }
+
+    /// A binary float operator; `InvalidParams` if either operand is empty.
+    fn float_add(&self, x: &[u8], y: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() || y.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// The same shape, for subtraction.
+    fn float_subtract(&self, x: &[u8], y: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() || y.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// The same shape, for multiplication.
+    fn float_multiply(&self, x: &[u8], y: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() || y.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// The same shape, for division.
+    fn float_divide(&self, x: &[u8], y: &[u8], _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() || y.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+
+    /// The same shape, for exponentiation.
+    fn float_power(&self, x: &[u8], _n: i32, _mode: i32, out: &mut [u8]) -> HostResult<usize> {
+        if x.is_empty() {
+            return Err(HostError::InvalidParams);
+        }
+        put(out, &[x[0]])
+    }
+}
+
+#[test]
+fn the_trait_is_implementable() {
+    let host = FakeHost::default();
+    let mut out = [0u8; HASH_LEN];
+
+    assert_eq!(host.get_ledger_sqn(&mut out), Ok(4));
+    assert_eq!(out[..4], [7, 0, 0, 0]);
+    assert_eq!(host.get_parent_ledger_time(&mut out), Ok(4));
+    assert_eq!(out[..4], [9, 0, 0, 0]);
+    assert_eq!(host.get_parent_ledger_hash(&mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 0xab);
+    assert_eq!(host.get_base_fee(&mut out), Ok(4));
+    assert_eq!(out[..4], [10, 0, 0, 0]);
+    assert_eq!(host.is_amendment_enabled(&[1; 32]), Ok(1));
+    assert_eq!(host.is_amendment_enabled(&[]), Ok(0));
+    assert_eq!(host.cache_ledger_obj(&[1; 32], 0), Ok(1));
+    assert_eq!(host.cache_ledger_obj(&[1; 32], 5), Ok(5));
+    assert_eq!(host.get_tx_field(5, &mut out), Ok(1));
+    assert_eq!(out[0], 5);
+    assert_eq!(host.get_current_ledger_obj_field(3, &mut out), Ok(1));
+    assert_eq!(out[0], 3);
+    assert_eq!(host.get_ledger_obj_field(2, 4, &mut out), Ok(2));
+    assert_eq!(out[..2], [2, 4]);
+    assert_eq!(host.get_tx_nested_field(&[9, 0, 0, 0], &mut out), Ok(2));
+    assert_eq!(out[..2], [9, 4]);
+    assert_eq!(
+        host.get_current_ledger_obj_nested_field(&[9, 0, 0, 0], &mut out),
+        Ok(2)
+    );
+    assert_eq!(out[..2], [4, 9]);
+    assert_eq!(
+        host.get_ledger_obj_nested_field(3, &[9, 0, 0, 0], &mut out),
+        Ok(2)
+    );
+    assert_eq!(out[..2], [3, 9]);
+    assert_eq!(host.get_tx_array_len(3), Ok(3));
+    assert_eq!(host.get_tx_array_len(-1), Err(HostError::NoArray));
+    assert_eq!(host.get_current_ledger_obj_array_len(3), Ok(4));
+    assert_eq!(
+        host.get_current_ledger_obj_array_len(-1),
+        Err(HostError::NoArray)
+    );
+    assert_eq!(host.get_ledger_obj_array_len(2, 3), Ok(5));
+    assert_eq!(host.get_ledger_obj_array_len(0, 3), Err(HostError::NoArray));
+    assert_eq!(host.get_tx_nested_array_len(&[9, 0, 0, 0]), Ok(4));
+    assert_eq!(
+        host.get_tx_nested_array_len(&[]),
+        Err(HostError::LocatorMalformed)
+    );
+    assert_eq!(
+        host.get_current_ledger_obj_nested_array_len(&[9, 0, 0, 0]),
+        Ok(5)
+    );
+    assert_eq!(
+        host.get_current_ledger_obj_nested_array_len(&[]),
+        Err(HostError::LocatorMalformed)
+    );
+    assert_eq!(
+        host.get_ledger_obj_nested_array_len(2, &[9, 0, 0, 0]),
+        Ok(6)
+    );
+    assert_eq!(
+        host.get_ledger_obj_nested_array_len(0, &[9, 0, 0, 0]),
+        Err(HostError::LocatorMalformed)
+    );
+    assert_eq!(host.check_signature(b"msg", b"sig", b"pk"), Ok(1));
+    assert_eq!(host.check_signature(b"msg", b"", b"pk"), Ok(0));
+    assert_eq!(host.account_keylet(&[7; 20], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.account_keylet(&[], &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.amm_keylet(&[1; 20], &[2; 40], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 20);
+    assert_eq!(
+        host.amm_keylet(&[1; 20], &[1; 20], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(host.check_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.check_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.credential_keylet(&[7; 20], &[8; 20], b"cred", &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.credential_keylet(&[], &[8; 20], b"cred", &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.delegate_keylet(&[7; 20], &[8; 20], &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.delegate_keylet(&[], &[8; 20], &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.deposit_preauth_keylet(&[7; 20], &[8; 20], &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 8);
+    assert_eq!(
+        host.deposit_preauth_keylet(&[7; 20], &[7; 20], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(host.did_keylet(&[7; 20], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.did_keylet(&[], &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.escrow_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.escrow_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.trust_line_keylet(&[7; 20], &[8; 20], &[1; 20], &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.trust_line_keylet(&[7; 20], &[7; 20], &[1; 20], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(
+        host.mptoken_issuance_keylet(&[7; 20], 5, &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.mptoken_issuance_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.mptoken_keylet(&[9; 24], &[8; 20], &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 9);
+    assert_eq!(
+        host.mptoken_keylet(&[], &[8; 20], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(
+        host.nftoken_offer_keylet(&[7; 20], 5, &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.nftoken_offer_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.offer_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.offer_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.oracle_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.oracle_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.paychannel_keylet(&[7; 20], &[8; 20], 5, &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.paychannel_keylet(&[7; 20], &[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(
+        host.permissioned_domain_keylet(&[7; 20], 5, &mut out),
+        Ok(HASH_LEN)
+    );
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.permissioned_domain_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.signer_list_keylet(&[7; 20], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.signer_list_keylet(&[], &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.ticket_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.ticket_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.vault_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.vault_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
+    assert_eq!(host.sha512_half(b"abc", &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 3);
+    assert_eq!(host.trace("hello", b"xy", TraceDataType::AsHex), Ok(()));
+    assert_eq!(host.update_data(b"abcd"), Ok(4));
+    assert_eq!(host.get_nft(&[7; 20], &[9; 32], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.get_nft(&[], &[9; 32], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(host.get_nft_issuer(&[9; 32], &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 9);
+    assert_eq!(
+        host.get_nft_issuer(&[], &mut out),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(host.get_nft_taxon(&[9; 32], &mut out), Ok(1));
+    assert_eq!(host.get_nft_flags(&[9; 32]), Ok(9));
+    assert_eq!(host.get_nft_flags(&[]), Err(HostError::InvalidParams));
+    assert_eq!(host.get_nft_transfer_fee(&[9; 32]), Ok(9));
+    assert_eq!(host.get_nft_sequence(&[9; 32], &mut out), Ok(1));
+    assert_eq!(host.float_from_int(5, 0, &mut out), Ok(1));
+    assert_eq!(host.float_from_uint(&[3; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_from_stamount(&[3; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_from_stnumber(&[3; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_to_int(&[3; 8], 0, &mut out), Ok(1));
+    let mut mant = [0u8; 8];
+    let mut exp = [0u8; 4];
+    assert_eq!(host.float_to_mant_exp(&[3; 8], &mut mant, &mut exp), Ok(2));
+    assert_eq!(host.float_from_mant_exp(5, 0, 0, &mut out), Ok(1));
+    assert_eq!(host.float_compare(&[9; 8], &[4; 8]), Ok(5));
+    assert_eq!(
+        host.float_compare(&[], &[4; 8]),
+        Err(HostError::InvalidParams)
+    );
+    assert_eq!(host.float_add(&[3; 8], &[4; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_subtract(&[3; 8], &[4; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_multiply(&[3; 8], &[4; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_divide(&[3; 8], &[4; 8], 0, &mut out), Ok(1));
+    assert_eq!(host.float_power(&[3; 8], 2, 0, &mut out), Ok(1));
+
+    assert_eq!(*host.traced.borrow(), ["hello/AsHex/2"]);
+}
+
+/// The error channel every declaration carries: an `Err` the VM turns into the
+/// wire's negative return code.
+#[test]
+fn a_failing_call_reports_its_error_code() {
+    let host = FakeHost::default();
+    let mut out = [0u8; 8];
+
+    assert_eq!(
+        host.get_current_ledger_obj_field(-1, &mut out),
+        Err(HostError::FieldNotFound)
+    );
+    assert_eq!(HostError::FieldNotFound.code(), -2);
+}
+
+/// A host reports the value's true length even when it cannot write it, which is
+/// what lets the engine answer `BufferTooSmall` on the guest's behalf.
+#[test]
+fn a_short_buffer_still_reports_the_true_length() {
+    let host = FakeHost::default();
+    let mut out = [0u8; 2];
+
+    assert_eq!(host.get_ledger_sqn(&mut out), Ok(4));
+    assert_eq!(
+        out,
+        [0, 0],
+        "nothing is written when the value does not fit"
+    );
+}
+
+/// The VM reaches the host as one shared trait object held in the wasmi `Store`,
+/// which is what the `&self` receivers are for.
+#[test]
+fn the_trait_is_callable_through_a_shared_trait_object() {
+    let fake = FakeHost::default();
+    let host: &dyn HostFunctions = &fake;
+    let mut out = [0u8; 4];
+
+    assert_eq!(host.get_ledger_sqn(&mut out), Ok(4));
+    assert_eq!(
+        host.trace("count", &1i64.to_le_bytes(), TraceDataType::Int64),
+        Ok(())
+    );
+
+    assert_eq!(*fake.traced.borrow(), ["count/Int64/8"]);
+}
+
+/// The whole table, written out: the one place the ABI's wire names and gas costs
+/// appear as literals, and a deliberate change-detector, since both are consensus
+/// input. Everything else reads `HostFunctionSpec::gas()` instead.
+///
+/// `ALL` is in declaration order, so comparing the whole vec pins the order and the
+/// membership too.
+#[test]
+fn the_spec_table_matches_the_declarations() {
+    let table: Vec<(&str, u64)> = HostFunctionSpec::ALL
+        .iter()
+        .map(|function| (function.wasm_name(), function.gas()))
+        .collect();
+
+    assert_eq!(
+        table,
+        [
+            ("ldgr_index", 60),
+            ("parent_ldgr_time", 60),
+            ("parent_ldgr_hash", 60),
+            ("base_fee", 60),
+            ("amendment_enabled", 100),
+            ("cache_le", 5000),
+            ("tx_field", 70),
+            ("home_le_field", 70),
+            ("le_field", 70),
+            ("tx_inner", 110),
+            ("home_le_inner", 110),
+            ("le_inner", 110),
+            ("tx_arr_len", 40),
+            ("home_le_arr_len", 40),
+            ("le_arr_len", 40),
+            ("tx_inner_arr_len", 70),
+            ("home_le_inner_arr_len", 70),
+            ("le_inner_arr_len", 70),
+            ("check_sig", 300),
+            ("accountroot_id", 350),
+            ("amm_id", 450),
+            ("check_id", 350),
+            ("credential_id", 350),
+            ("delegate_id", 350),
+            ("deposit_preauth_id", 350),
+            ("did_id", 350),
+            ("escrow_id", 350),
+            ("trustline_id", 400),
+            ("mpt_issuance_id", 350),
+            ("mptoken_id", 500),
+            ("nft_offer_id", 350),
+            ("offer_id", 350),
+            ("oracle_id", 350),
+            ("paychan_id", 350),
+            ("permissioned_domain_id", 350),
+            ("signers_id", 350),
+            ("ticket_id", 350),
+            ("vault_id", 350),
+            ("sha512_half", 2000),
+            ("trace", 30),
+            ("set_data", 1000),
+            ("nft_uri", 5000),
+            ("nft_issuer", 70),
+            ("nft_taxon", 60),
+            ("nft_flags", 60),
+            ("nft_xfer_fee", 60),
+            ("nft_serial", 60),
+            ("float_from_int", 100),
+            ("float_from_uint", 130),
+            ("float_from_stamount", 150),
+            ("float_from_stnumber", 150),
+            ("float_to_int", 130),
+            ("float_to_mant_exp", 130),
+            ("float_from_mant_exp", 100),
+            ("float_cmp", 80),
+            ("float_add", 160),
+            ("float_sub", 160),
+            ("float_mult", 300),
+            ("float_div", 300),
+            ("float_pow", 5500),
+        ]
+    );
+}
+
+/// The other half of the wire vocabulary, and the same change-detector argument: the
+/// codes are what a guest passes, so they are pinned as literals here. `ALL` is in code
+/// order, so the round trip pins the discriminants and not just the membership.
+#[test]
+fn every_trace_data_type_survives_the_wire() {
+    let codes: Vec<i32> = TraceDataType::ALL.iter().map(|t| t.code()).collect();
+
+    assert_eq!(codes, [1, 2, 3, 4, 5, 6, 7]);
+    for &data_type in TraceDataType::ALL {
+        assert_eq!(TraceDataType::from_code(data_type.code()), Some(data_type));
+    }
+}
+
+/// A code no declaration names is refused rather than read as a neighbouring type.
+/// Zero is the one worth naming: it is what a guest sends by omission.
+#[test]
+fn an_unnamed_trace_data_type_code_is_refused() {
+    for code in [0, -1, 8, i32::MAX, i32::MIN] {
+        assert_eq!(TraceDataType::from_code(code), None, "code {code}");
+    }
+}
+
+/// `ALL` is what a wasm engine iterates to register imports, so no two declarations
+/// may collapse to the same wire name. The table above pins membership and order;
+/// this adds only uniqueness, and restates nothing.
+#[test]
+fn every_variant_appears_in_all_exactly_once() {
+    let names: HashSet<&str> = HostFunctionSpec::ALL
+        .iter()
+        .map(|function| function.wasm_name())
+        .collect();
+
+    assert_eq!(names.len(), HostFunctionSpec::ALL.len());
+}
+
+/// Both accessors are `const`, so an engine can build its import and gas tables at
+/// compile time rather than on every invocation. The assertions sit in `const`
+/// blocks so they are checked while compiling, which is the claim; the values
+/// themselves are pinned above.
+#[test]
+fn the_table_is_usable_in_const_context() {
+    const NAME: &str = HostFunctionSpec::Trace.wasm_name();
+    const GAS: u64 = HostFunctionSpec::Trace.gas();
+
+    const { assert!(!NAME.is_empty()) };
+    const { assert!(GAS > 0) };
+}

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

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

crates/xrpl-wasm-testkit/Cargo.toml

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

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

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

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

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

crates/xrpl-wasm-vm/Cargo.toml

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

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

@@ -0,0 +1,824 @@
+use crate::region::Region;
+use crate::vm::{MAX_FIELD_BYTES, VmState};
+use 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))
+}
+
+/// [`Region::read`] of the guest's memory, for a call that reads and writes nothing
+/// back (`trace`).
+pub(crate) fn read_borrowed<'a>(
+    caller: &'a Caller<'_, VmState<'_>>,
+    input: Region,
+) -> CallResult<&'a [u8]> {
+    let mem = memory(caller)?;
+    Ok(input.read(mem.data(caller))?)
+}
+
+/// Decode a guest `u32` argument — a keylet's sequence number or document id — from
+/// its four little-endian bytes, carried on to the host as its `i32` bit pattern.
+///
+/// The ABI transports these as a 4-byte region rather than a wasm scalar (the guest
+/// SDK passes `seq.to_le_bytes()`), so the region must be exactly four bytes;
+/// `InvalidParams` otherwise.
+pub(crate) fn read_u32_arg(bytes: &[u8]) -> HostResult<i32> {
+    let arr: [u8; 4] = bytes.try_into().map_err(|_| HostError::InvalidParams)?;
+    Ok(i32::from_le_bytes(arr))
+}
+
+/// Service a call whose answer is bytes, written straight into the guest's output
+/// region.
+///
+/// **`fill` returns the value's true length, not what it wrote**: a host holding 64
+/// bytes and offered room for 4 writes nothing and answers `64`, which is how the
+/// guest learns the size to ask for. So `n` is bounded by neither the region, the
+/// cap, nor the budget, and all three checks below are reachable.
+pub(crate) fn write_into(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    fill: impl FnOnce(&dyn HostFunctions, &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let range = out.range()?;
+    let cap = range.len();
+    let mem = memory(caller)?;
+    let host: &dyn HostFunctions = caller.data().host;
+    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 borrow any number of input
+/// regions with [`Region::read`] — which a `&mut` view of that memory would forbid.
+/// That is why the answer goes through a buffer instead of straight into the guest
+/// as [`write_into`]'s does.
+///
+/// **The host is never told the guest's capacity**: it is offered the whole buffer
+/// and reports the value's true length, so the fit is decided here, with nothing yet
+/// in guest memory. A refused value therefore reaches it in no part.
+///
+/// The output is judged after the inputs, so a call with both bad reports the
+/// input's verdict. `NoMemExported` precedes both: there is no memory to validate a
+/// region against.
+pub(crate) fn write_buffered(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    // One borrow split in two: the guest's bytes for the inputs, the store data for
+    // the output buffer. Taking them together is what keeps the inputs borrowed
+    // rather than copied out.
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    let n = call(host, data, &mut state.out_buffer[..])?;
+
+    // `out` is checked here rather than before the call: the inputs are judged
+    // first, so a call with both malformed reports the input's verdict.
+    let range = out.range()?;
+    let cap = range.len();
+    if n > MAX_FIELD_BYTES {
+        return Err(HostError::DataFieldTooLarge.into());
+    }
+    let buf = data.get_mut(range).ok_or(HostError::PointerOutOfBounds)?;
+    if n > cap {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    charge_transfer(state, n)?;
+    buf[..n].copy_from_slice(&state.out_buffer[..n]);
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "`n > MAX_FIELD_BYTES` returned above, and the cap is far inside i32"
+    )]
+    let n = n as i32;
+    Ok(n)
+}
+
+/// The mantissa and exponent widths `float_to_mant_exp` writes: an `i64` and an `i32`.
+/// Fixed by the ABI, not the guest, so the split is a constant rather than a reported
+/// length.
+const MANTISSA_BYTES: usize = 8;
+const EXPONENT_BYTES: usize = 4;
+
+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: Region,
+    exponent_out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    // The scratch buffer is split at the fixed mantissa width: the host fills the first
+    // eight bytes with the mantissa and the next four with the exponent.
+    let (mant_buf, exp_buf) = state.out_buffer.split_at_mut(MANTISSA_BYTES);
+    let mant_buf = &mut mant_buf[..MANTISSA_BYTES];
+    let exp_buf = &mut exp_buf[..EXPONENT_BYTES];
+
+    let total = call(host, data, mant_buf, exp_buf)?;
+
+    // Both buffers are fixed-width and were offered whole, so the only length the host
+    // can correctly report is their sum. Anything else is the host contradicting the
+    // ABI: with the widths in doubt, part of what would be copied out is whatever the
+    // previous call left in the buffer, so none of it is copied.
+    if total != MANTISSA_BYTES + EXPONENT_BYTES {
+        return Err(HostError::InternalFatal.into());
+    }
+
+    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)]
+mod tests {
+    use super::*;
+    use crate::vm::TRANSFER_LIMIT_BYTES;
+    use std::cell::Cell;
+    use wasmi::StoreLimitsBuilder;
+    use xrpl_host_functions::TraceDataType;
+
+    /// `charge_transfer` takes the store data, which has to hold a host.
+    struct UncalledHost;
+
+    impl HostFunctions for UncalledHost {
+        fn get_ledger_sqn(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_time(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_hash(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_base_fee(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn is_amendment_enabled(&self, _amendment: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn cache_ledger_obj(&self, _obj_id: &[u8], _cache_idx: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_field(
+            &self,
+            _cache_idx: i32,
+            _field: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_field(&self, _locator: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_field(
+            &self,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_field(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_array_len(&self, _cache_idx: i32, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_array_len(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_signature(
+            &self,
+            _message: &[u8],
+            _signature: &[u8],
+            _pubkey: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn account_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn amm_keylet(&self, _asset1: &[u8], _asset2: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn credential_keylet(
+            &self,
+            _subject: &[u8],
+            _issuer: &[u8],
+            _credential_type: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn delegate_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn deposit_preauth_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn did_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn escrow_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trust_line_keylet(
+            &self,
+            _account1: &[u8],
+            _account2: &[u8],
+            _currency: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_issuance_keylet(
+            &self,
+            _issuer: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_keylet(
+            &self,
+            _mptid: &[u8],
+            _holder: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn nftoken_offer_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn offer_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn oracle_keylet(
+            &self,
+            _account: &[u8],
+            _doc_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn paychannel_keylet(
+            &self,
+            _account: &[u8],
+            _destination: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn permissioned_domain_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn signer_list_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn ticket_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn vault_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn sha512_half(&self, _data: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trace(&self, _msg: &str, _data: &[u8], _data_type: TraceDataType) -> HostResult<()> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn update_data(&self, _data: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft(&self, _account: &[u8], _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_issuer(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_taxon(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_flags(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_transfer_fee(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_sequence(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_int(&self, _x: i64, _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_uint(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stamount(
+            &self,
+            _amount: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stnumber(
+            &self,
+            _number: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_int(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_mant_exp(
+            &self,
+            _x: &[u8],
+            _mantissa_out: &mut [u8],
+            _exponent_out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_mant_exp(
+            &self,
+            _mantissa: i64,
+            _exponent: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_compare(&self, _x: &[u8], _y: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_add(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_subtract(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_multiply(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_divide(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_power(
+            &self,
+            _x: &[u8],
+            _n: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+    }
+
+    fn state(budget: u64) -> VmState<'static> {
+        VmState {
+            host: &UncalledHost,
+            mem_limits: StoreLimitsBuilder::new().build(),
+            transfer_budget: Cell::new(budget),
+            memory: None,
+            out_buffer: [0u8; MAX_FIELD_BYTES],
+        }
+    }
+
+    /// `wasmi::Error` is not `PartialEq`, so a test expecting the guest-visible
+    /// channel says so by going through here.
+    fn wire(result: CallResult<i32>) -> i32 {
+        to_wire(result)
+            .unwrap_or_else(|trap| panic!("expected a guest-visible status, got a trap: {trap}"))
+    }
+
+    #[test]
+    fn a_success_becomes_the_value_and_an_error_becomes_its_code() {
+        assert_eq!(wire(Ok(0)), 0);
+        assert_eq!(wire(Ok(32)), 32);
+        assert_eq!(wire(Err(HostError::BufferTooSmall.into())), -3);
+    }
+
+    /// The codes a host may answer that a contract must not see, and the fault each
+    /// becomes. Written out rather than derived from `From<HostError>`, which is what
+    /// they are asserting.
+    const STOPS_THE_RUN: [(HostError, Fault); 3] = [
+        (HostError::InternalFatal, Fault::Internal),
+        (HostError::Unimplemented, Fault::Internal),
+        (HostError::NoMemExported, Fault::NoMemory),
+    ];
+
+    /// Every fault, so the two tests below are the whole set and not a sample.
+    /// `From<Fault> for RunError` is what forces a fault added later to be
+    /// considered; this is what forces it to be tested.
+    const ALL_FAULTS: [Fault; 3] = [Fault::OutOfGas, Fault::Internal, Fault::NoMemory];
+
+    #[test]
+    fn a_code_that_stops_the_run_converts_to_its_fault() {
+        for (error, fault) in STOPS_THE_RUN {
+            assert_eq!(CallError::from(error), CallError::Fatal(fault), "{error:?}");
+        }
+    }
+
+    /// Over `HostError::ALL`, so it is the whole ABI and not a sample: a code added
+    /// to the ABI arrives already asserted to reach the guest as itself, and stopping
+    /// the run on it is then a change someone has to come and make.
+    ///
+    /// `OutOfTransferLimit` is the row worth reading twice: the one budget a
+    /// contract can be expected to handle, so it is told no rather than killed.
+    #[test]
+    fn every_other_code_reaches_the_guest_as_itself() {
+        for &error in HostError::ALL {
+            if STOPS_THE_RUN.iter().any(|&(stops, _)| stops == error) {
+                continue;
+            }
+            assert_eq!(CallError::from(error), CallError::Code(error), "{error:?}");
+            assert_eq!(wire(Err(error.into())), error.code(), "{error:?}");
+        }
+    }
+
+    /// The trap carries the fault, so `run` can name the outcome without parsing a
+    /// message.
+    #[test]
+    fn a_fault_becomes_a_trap_carrying_it() {
+        for fault in ALL_FAULTS {
+            let trap = to_wire(Err(CallError::Fatal(fault)))
+                .expect_err("a fault must not reach the guest as a code");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    /// The result-less path splits the same two channels differently: a fault still
+    /// stops the run, and every code is dropped, since `trace` has no return value to
+    /// carry it. Over `HostError::ALL` for the reason above — a code added to the ABI
+    /// arrives asserted against both paths.
+    #[test]
+    fn a_call_with_no_result_drops_a_code_and_traps_on_a_fault() {
+        assert!(dropped(Ok(())).is_ok());
+
+        for &error in HostError::ALL {
+            if let CallError::Code(code) = CallError::from(error) {
+                assert!(
+                    dropped(Err(CallError::Code(code))).is_ok(),
+                    "{error:?} has no channel to the guest and must be dropped"
+                );
+            }
+        }
+
+        for fault in ALL_FAULTS {
+            let trap =
+                dropped(Err(CallError::Fatal(fault))).expect_err("a fault must stop the run");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    #[test]
+    fn a_transfer_spends_the_budget() {
+        let state = state(100);
+
+        assert_eq!(charge_transfer(&state, 30), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 70);
+        assert_eq!(charge_transfer(&state, 70), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The budget bounds the total, so the transfer that would overrun it is
+    /// refused whole rather than partially charged.
+    #[test]
+    fn a_transfer_past_the_budget_is_refused_and_charges_nothing() {
+        let state = state(100);
+
+        assert_eq!(
+            charge_transfer(&state, 101),
+            Err(HostError::OutOfTransferLimit)
+        );
+        assert_eq!(
+            state.transfer_budget.get(),
+            100,
+            "a refusal must not charge"
+        );
+        assert_eq!(charge_transfer(&state, 100), Ok(()));
+        assert_eq!(
+            charge_transfer(&state, 1),
+            Err(HostError::OutOfTransferLimit)
+        );
+    }
+
+    #[test]
+    fn transferring_nothing_costs_nothing() {
+        let state = state(0);
+
+        assert_eq!(charge_transfer(&state, 0), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The field cap holds one call to a small share of the run's budget, so the
+    /// budget bounds a run rather than a call. An inequality, not the two values:
+    /// those are pinned in `vm.rs`.
+    #[test]
+    fn no_single_value_can_exhaust_the_run_budget() {
+        assert!(
+            (MAX_FIELD_BYTES as u64) * 64 <= TRANSFER_LIMIT_BYTES,
+            "one {MAX_FIELD_BYTES}-byte value against a {TRANSFER_LIMIT_BYTES}-byte budget"
+        );
+    }
+}

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

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

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

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

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

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

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

@@ -0,0 +1,404 @@
+use std::cell::Cell;
+use std::fmt;
+use std::sync::LazyLock;
+use wasmi::{
+    Config, Engine, Export, Linker, Memory, Module, Store, StoreLimits, StoreLimitsBuilder,
+    TrapCode,
+};
+use xrpl_host_functions::HostFunctions;
+
+use crate::abi::{FatalHostError, Fault};
+use crate::preflight::entry_point_fault;
+use crate::register::register_host_functions;
+
+/// wasm linear-memory page size, fixed by the wasm spec (64 KiB).
+const WASM_PAGE_BYTES: u32 = 64 * 1024;
+
+/// Linear-memory page cap.
+pub const MAX_MEMORY_PAGES: u32 = 128;
+
+/// [`MAX_MEMORY_PAGES`] in bytes: 8 MiB.
+pub const MAX_MEMORY_BYTES: usize = (MAX_MEMORY_PAGES * WASM_PAGE_BYTES) as usize;
+
+/// Cap on a table's element count.
+///
+/// A table entry is 8 bytes and wasmi materializes every one of them inside
+/// `instantiate_and_start` — before the guest's first instruction, so no gas charge
+/// can reach the cost. Without this cap the ceiling is the validator's, `u32::MAX`
+/// entries, which a module asks for in five bytes of LEB128 and pays for in ~34 GiB.
+pub const MAX_TABLE_ELEMENTS: usize = 1024;
+
+/// Total bytes the host may write into guest memory in one [`run`], separate from
+/// gas.
+///
+/// One direction only. What the guest passes in is not charged: it reaches the host
+/// as a borrowed slice of guest memory, capped per value at [`MAX_FIELD_BYTES`] by
+/// `Region::read` and in number by gas, and a host that keeps a copy (`update_data`)
+/// bounds it on its own side.
+pub const TRANSFER_LIMIT_BYTES: u64 = 1 << 20;
+
+/// Size cap on any single value crossing the boundary, in either direction; over
+/// it is `DataFieldTooLarge`.
+///
+/// A protocol limit: `kMaxWasmDataLength` in `include/xrpl/protocol/Protocol.h`.
+pub const MAX_FIELD_BYTES: usize = 1024;
+
+/// State threaded through every host call, stored in the wasmi [`Store`].
+pub(crate) struct VmState<'h> {
+    pub(crate) host: &'h dyn HostFunctions,
+    /// Enforces [`store_limits`] via `Store::limiter`, which needs a `&mut` into it
+    /// from `&mut VmState` — hence a field rather than a local.
+    pub(crate) mem_limits: StoreLimits,
+    /// Remaining transfer budget for this run ([`TRANSFER_LIMIT_BYTES`]).
+    ///
+    /// A `Cell` because it is decremented from a shared `&Caller`. One thread per
+    /// invocation touches the store, so the lack of `Sync` costs nothing.
+    ///
+    /// TODO: the extra charge for an unaligned field copy has nothing to attach to
+    /// until this ABI gains a `FieldLocator` host function.
+    pub(crate) transfer_budget: Cell<u64>,
+    /// The guest's linear memory, resolved once by [`run`] after instantiation so
+    /// no host call pays for an export lookup.
+    ///
+    /// Caching the handle is sound because a [`Memory`] is an arena index, not a
+    /// pointer to the bytes: it survives `memory.grow`, and `data`/`data_mut`
+    /// re-derive the slice per call.
+    ///
+    /// The handle is scoped to one store, so this assumes **one module, one
+    /// instance, one store per `run`**. Module linking or nested execution would
+    /// have to resolve per instance: a cached handle would serve a call against the
+    /// wrong instance's memory, which is a wrong answer rather than an error.
+    pub(crate) memory: Option<Memory>,
+    /// Where a host writes a value before [`crate::abi::write_buffered`] copies it
+    /// to the guest. One buffer per run, so no call zero-fills one of its own.
+    ///
+    /// Inline rather than boxed: the store's data is built once and then only
+    /// borrowed, so a kilobyte in it costs a move where a `Box` costs an
+    /// allocation. A local would cost neither, but `forbid(unsafe_code)` means a
+    /// stack buffer is zero-filled — per call, which is the cost this removes.
+    pub(crate) out_buffer: [u8; MAX_FIELD_BYTES],
+}
+
+/// Outcome of running an escrow contract to completion.
+#[derive(Debug)]
+pub struct RunOutcome {
+    /// The value returned by the exported entry point (`finish`): `> 0` means
+    /// allow the escrow to finish.
+    pub result: i32,
+    /// Fuel (gas) consumed by the whole invocation — guest instructions plus
+    /// the per-call host charges.
+    pub fuel_used: u64,
+}
+
+/// Why a run produced no result. Each variant is one outcome for the caller to
+/// map to a TER.
+#[derive(Debug)]
+pub enum RunError {
+    /// `wasm` is not a valid module under this engine's configuration.
+    Compile(String),
+    /// The module compiled but the engine would not accept it: an import the
+    /// linker does not define, or an initial memory past the page cap. Not guest
+    /// code failing — a start section that traps is [`RunError::Trap`].
+    Instantiate(String),
+    /// No export named `function_name` with signature `() -> i32`: absent, not a
+    /// function, or a function of another type — which the detail tells apart.
+    EntryPoint(String),
+    /// Gas exhausted — by the guest's own instructions or by a host call's
+    /// charge. [`RunFailure::fuel_used`] is the whole limit.
+    OutOfGas,
+    /// The host could not serve a call.
+    Internal,
+    /// A host call had 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
+    /// to resolve the memory from.
+    NoMemory,
+    /// The guest trapped: `unreachable`, division by zero, an out-of-bounds
+    /// access, or `memory.grow` past the page cap. Wherever the guest was
+    /// executing, including a start section during instantiation.
+    Trap(String),
+}
+
+impl fmt::Display for RunError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            RunError::Compile(detail) => write!(f, "compile: {detail}"),
+            RunError::Instantiate(detail) => write!(f, "instantiate: {detail}"),
+            // The detail says which of the entry point's failures this is, since
+            // "no entry point" would be wrong for an export of the wrong type.
+            RunError::EntryPoint(detail) => write!(f, "{detail}"),
+            RunError::OutOfGas => write!(f, "out of gas"),
+            RunError::Internal => write!(f, "internal error"),
+            RunError::NoMemory => write!(f, "no exported memory"),
+            RunError::Trap(detail) => write!(f, "trap: {detail}"),
+        }
+    }
+}
+
+/// A failed run, with the gas it still owes: a contract that traps or exhausts
+/// its gas is charged for what it burned.
+#[derive(Debug)]
+pub struct RunFailure {
+    pub error: RunError,
+    /// Fuel consumed before the failure. The whole limit when gas ran out; `0`
+    /// when the module never ran.
+    pub fuel_used: u64,
+}
+
+impl fmt::Display for RunFailure {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} (fuel used: {})", self.error, self.fuel_used)
+    }
+}
+
+impl RunFailure {
+    /// A failure with no fuel accounted: it stopped the run at or before the guest's
+    /// first instruction, or under a store with no meter to read.
+    fn owing_nothing(error: RunError) -> RunFailure {
+        RunFailure {
+            error,
+            fuel_used: 0,
+        }
+    }
+}
+
+/// Fuel spent out of `gas`: the one place a run's cost is measured, so success,
+/// trap and refusal all report it the same way.
+///
+/// `Store::get_fuel` fails only on a store without fuel metering, which
+/// [`build_wasm_engine`] rules out and `run`'s `set_fuel` would already have
+/// caught — so a failure here is a defect in this crate. It must not become a
+/// number: `0` forgives a run its whole cost, `gas` charges an untouched one for
+/// everything. [`RunError::Internal`] instead.
+fn fuel_used(store: &Store<VmState<'_>>, gas: u64) -> Result<u64, RunError> {
+    store
+        .get_fuel()
+        .map(|remaining| gas.saturating_sub(remaining))
+        .map_err(|_| RunError::Internal)
+}
+
+/// Report `error` with the run's cost attached. A cost that cannot be read replaces
+/// the outcome rather than being invented — see [`fuel_used`].
+fn failed(store: &Store<VmState<'_>>, gas: u64, error: RunError) -> RunFailure {
+    match fuel_used(store, gas) {
+        Ok(fuel_used) => RunFailure { error, fuel_used },
+        Err(unmetered) => RunFailure::owing_nothing(unmetered),
+    }
+}
+
+/// The outcome a `wasmi::Error` names for itself, if any, rather than leaving it to
+/// the stage that raised it.
+///
+/// Two ways a run halts mid-flight: a host call that could not be served, which
+/// carries a [`FatalHostError`] saying which condition it was, and the guest's own
+/// instructions exhausting the meter, which wasmi raises as `OutOfFuel`.
+///
+/// Both can happen anywhere the guest executes — including a start section, which
+/// is guest code running during instantiation — so every stage from there on asks
+/// this before naming a failure after itself.
+fn guest_halted(error: &wasmi::Error) -> Option<RunError> {
+    if let Some(fatal) = error.downcast_ref::<FatalHostError>() {
+        return Some(fatal.0.into());
+    }
+    (error.as_trap_code() == Some(TrapCode::OutOfFuel)).then_some(RunError::OutOfGas)
+}
+
+/// Why instantiation failed, once [`guest_halted`] has ruled out the two conditions
+/// that can arise anywhere.
+///
+/// A start section is guest code, so it can trap on its own — `unreachable`, a
+/// division by zero, an out-of-bounds access — and a trap is the guest's fault
+/// wherever it happens. Naming that after the *stage* would file it beside the
+/// module faults a caller treats as its own defect, and charge nothing for
+/// instructions the contract burned. What is left for [`RunError::Instantiate`] is a
+/// module the linker or the store would not accept at all.
+fn instantiation_failure(error: &wasmi::Error) -> RunError {
+    match error.as_trap_code() {
+        Some(_) => RunError::Trap(error.to_string()),
+        None => RunError::Instantiate(error.to_string()),
+    }
+}
+
+/// The outcome a [`Fault`] is: the one place a stopped call becomes a stopped run.
+///
+/// Total and one arm each, because a `Fault` is only ever a condition that stops the
+/// run — the guest-visible codes cannot reach here, which is what
+/// [`crate::abi::CallError`] buys. A fault added later has no arm and does not
+/// compile.
+impl From<Fault> for RunError {
+    fn from(fault: Fault) -> RunError {
+        match fault {
+            Fault::OutOfGas => RunError::OutOfGas,
+            Fault::Internal => RunError::Internal,
+            Fault::NoMemory => RunError::NoMemory,
+        }
+    }
+}
+
+/// The process-wide wasmi engine, built once on first use.
+///
+/// The configuration is consensus-fixed and identical for every invocation, and an
+/// [`Engine`] is an internally `Arc`ed `Send + Sync` handle, so one shared engine
+/// serves concurrent [`run`] calls.
+pub(crate) fn wasm_engine() -> &'static Engine {
+    static ENGINE: LazyLock<Engine> = LazyLock::new(build_wasm_engine);
+    &ENGINE
+}
+
+/// Build the wasmi engine the escrow VM requires: deterministic, minimal
+/// features, fuel metering on.
+fn build_wasm_engine() -> Engine {
+    let mut config = Config::default();
+    config.consume_fuel(true);
+    config.ignore_custom_sections(true);
+    config.wasm_mutable_global(false);
+    config.wasm_multi_value(false);
+    config.wasm_sign_extension(false);
+    config.wasm_saturating_float_to_int(false);
+    config.wasm_bulk_memory(false);
+    config.wasm_reference_types(false);
+    config.wasm_tail_call(false);
+    config.wasm_extended_const(false);
+    config.floats(false);
+    config.wasm_multi_memory(false);
+    config.wasm_custom_page_sizes(false);
+    config.wasm_memory64(false);
+    config.wasm_wide_arithmetic(false);
+    // TODO: enable option to reject wasm code containing start section after wasmi 2.0 release
+    Engine::new(&config)
+}
+
+/// Every resource ceiling a run is given, in one place.
+///
+/// The two *size* caps are what a contract can reach today. The three *count* caps
+/// are set to 1 although [`build_wasm_engine`] already forces each: turning
+/// `wasm_reference_types` on would let a module declare up to
+/// `wasmparser::MAX_WASM_TABLES` tables, `wasm_multi_memory` likewise for memories,
+/// and both size caps are **per table and per memory, not aggregate** — so a feature
+/// flag flipped in isolation would multiply the ceiling by a hundred rather than
+/// leave it be. The counts are what keeps those two decisions independent.
+///
+/// wasmi enforces the counts by asking the limiter before it allocates
+/// (`can_create_more_instances`/`_memories`/`_tables`); they default to 10000, so
+/// leaving them unset is not the same as their being unreachable.
+fn store_limits() -> StoreLimits {
+    StoreLimitsBuilder::new()
+        .memory_size(MAX_MEMORY_BYTES)
+        .table_elements(MAX_TABLE_ELEMENTS)
+        .instances(1)
+        .tables(1)
+        .memories(1)
+        .trap_on_grow_failure(true)
+        .build()
+}
+
+/// Compile `wasm` for this engine.
+///
+/// The one path to a [`Module`]: the configuration is what decides whether a
+/// contract is valid at all, so [`run`] and [`crate::check`] must not be able to
+/// compile against different ones.
+pub(crate) fn compile(wasm: &[u8]) -> Result<Module, String> {
+    Module::new(wasm_engine(), wasm).map_err(|e| e.to_string())
+}
+
+/// Run a contract: compile `wasm`, give it `gas` fuel, service its host
+/// calls through `host`, and call the exported `function_name`.
+pub fn run<'h>(
+    wasm: &[u8],
+    gas: u64,
+    host: &'h dyn HostFunctions,
+    function_name: &str,
+) -> Result<RunOutcome, RunFailure> {
+    let engine = wasm_engine();
+    let module =
+        compile(wasm).map_err(|detail| RunFailure::owing_nothing(RunError::Compile(detail)))?;
+
+    let mut store = Store::new(
+        engine,
+        VmState {
+            host,
+            mem_limits: store_limits(),
+            transfer_budget: Cell::new(TRANSFER_LIMIT_BYTES),
+            memory: None,
+            out_buffer: [0u8; MAX_FIELD_BYTES],
+        },
+    );
+
+    store
+        .set_fuel(gas)
+        .map_err(|_| RunFailure::owing_nothing(RunError::Internal))?;
+    store.limiter(|state| &mut state.mem_limits);
+
+    let mut linker = Linker::<VmState<'h>>::new(engine);
+    register_host_functions(&mut linker)
+        .map_err(|_| RunFailure::owing_nothing(RunError::Internal))?;
+
+    let instance = match linker.instantiate_and_start(&mut store, &module) {
+        Ok(instance) => instance,
+        Err(e) => {
+            let error = guest_halted(&e).unwrap_or_else(|| instantiation_failure(&e));
+            return Err(failed(&store, gas, error));
+        }
+    };
+    store.data_mut().memory = instance.exports(&store).find_map(Export::into_memory);
+
+    let function = match instance.get_typed_func::<(), i32>(&store, function_name) {
+        Ok(function) => function,
+        Err(e) => {
+            let found = instance
+                .get_export(&store, function_name)
+                .map(|export| export.ty(&store));
+            let error =
+                RunError::EntryPoint(format!("{}: {e}", entry_point_fault(found, function_name)));
+            return Err(failed(&store, gas, error));
+        }
+    };
+
+    let result = match function.call(&mut store, ()) {
+        Ok(result) => result,
+        Err(e) => {
+            let error = guest_halted(&e).unwrap_or_else(|| RunError::Trap(e.to_string()));
+            return Err(failed(&store, gas, error));
+        }
+    };
+
+    let fuel_used = fuel_used(&store, gas).map_err(RunFailure::owing_nothing)?;
+    Ok(RunOutcome { result, fuel_used })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_engine_is_one_engine() {
+        assert!(Engine::same(wasm_engine(), wasm_engine()));
+    }
+
+    /// One instance, one table, one memory — asserted here rather than through a
+    /// module, because no module can reach these. `wasm_reference_types(false)` and
+    /// `wasm_multi_memory(false)` make a module declaring a second table or memory
+    /// fail *validation*, so a run never gets far enough to consult the limiter.
+    /// That is exactly why the counts are worth pinning: they are the ceiling that
+    /// survives one of those flags being turned on, and nothing else would fail if
+    /// they were silently dropped.
+    #[test]
+    fn the_store_grants_one_of_each_thing_a_module_can_own() {
+        use wasmi::ResourceLimiter;
+
+        let limits = store_limits();
+        assert_eq!(limits.instances(), 1);
+        assert_eq!(limits.tables(), 1);
+        assert_eq!(limits.memories(), 1);
+    }
+
+    /// The only place these numbers appear as literals; every other test derives
+    /// them from the constants.
+    #[test]
+    fn the_limits_are_the_protocol_limits() {
+        assert_eq!(MAX_MEMORY_PAGES, 128, "linear-memory page cap");
+        assert_eq!(MAX_MEMORY_BYTES, 8 * 1024 * 1024, "page cap in bytes");
+        assert_eq!(MAX_TABLE_ELEMENTS, 1024, "table-element cap");
+        assert_eq!(MAX_FIELD_BYTES, 1024, "kMaxWasmDataLength");
+        assert_eq!(TRANSFER_LIMIT_BYTES, 1 << 20, "kWasmTransferLimit");
+    }
+}

crates/xrpl-wasm-vm/tests/budgets.rs

@@ -0,0 +1,922 @@
+//! The two budgets a run spends: gas (fuel), and the transfer limit on bytes
+//! crossing the boundary. Both are consensus input, so several of these tests
+//! assert exact numbers.
+
+mod support;
+
+use support::{
+    Answer, EMPTY_REGION, FakeHost, ONE_PAGE, PLENTY_OF_GAS, code, import, module, run,
+    run_with_gas, trace_call,
+};
+use xrpl_host_functions::{HASH_LEN, HostError, HostFunctionSpec, TraceDataType};
+use xrpl_wasm_vm::{MAX_FIELD_BYTES, RunError, TRANSFER_LIMIT_BYTES};
+
+// ---------------------------------------------------------------------------
+// Gas
+// ---------------------------------------------------------------------------
+
+/// The fuel a module of `body` burns, given gas to spare.
+fn fuel_for(body: &str, parts: &[&str], host: &FakeHost) -> u64 {
+    let wat = module(parts, body);
+    run(&wat, host).expect("the module should run").fuel_used
+}
+
+/// The fuel a module burns doing nothing but returning a constant; every figure
+/// below builds on it. wasmi's number, pinned deliberately because wasmi's fuel
+/// table is consensus input.
+const EMPTY_MODULE_FUEL: u64 = 30;
+
+/// wasmi's own fuel for a host call whose operands are all constants under 64: 14
+/// per `*.const`, plus 1 for the call. Our gas sits on top.
+///
+/// The formula holds only under 64, because wasmi widens a constant's encoding
+/// above that, each tier costing 7 more. Every call in [`call_for`] keeps its
+/// operands small for that reason; one with a larger constant fails here by a
+/// multiple of 7.
+fn wasmi_call_fuel(small_const_operands: u64) -> u64 {
+    14 * small_const_operands + 1
+}
+
+/// What wasmi charges on top of that for a call to a function with no result —
+/// `trace`'s shape, and nothing else in the ABI. Per call, not per module. Measured
+/// and pinned like the figures above.
+const WASMI_NO_RESULT_FUEL: u64 = 14;
+
+/// wasmi's fuel for one `(drop …)`, which is how a module makes more than one call
+/// and keeps only the last result. Pinned like the two above.
+const WASMI_DROP_FUEL: u64 = 21;
+
+/// The wasm a test needs in order to call one host function: the `(import …)`
+/// declaration, a call with small-constant operands, and how many it pushes.
+struct Call {
+    import: &'static str,
+    call: &'static str,
+    operands: u64,
+    /// Whether the call leaves an `i32` behind. `trace` does not, which is why
+    /// [`Call::body`] ends every module with a constant instead of the call.
+    yields: bool,
+}
+
+impl Call {
+    /// `n` calls in a row, leaving one `i32` for the module to return: the last
+    /// answer where there is one, and a constant where the call has none.
+    fn body(&self, n: usize) -> String {
+        if self.yields {
+            format!(
+                "{}{}",
+                format!("(drop {}) ", self.call).repeat(n - 1),
+                self.call
+            )
+        } else {
+            format!("{}(i32.const 0)", format!("{} ", self.call).repeat(n))
+        }
+    }
+
+    /// What [`Call::body`] burns beside the calls' own gas and the module's floor:
+    /// one `drop` between consecutive answers, or wasmi's own surcharge on a call
+    /// that has none.
+    fn overhead(&self, n: u64) -> u64 {
+        if self.yields {
+            (n - 1) * WASMI_DROP_FUEL
+        } else {
+            n * WASMI_NO_RESULT_FUEL
+        }
+    }
+}
+
+/// The test wasm for each host function. The `match` is exhaustive, so a function
+/// added to the ABI fails to compile until it has wasm here, and iterating
+/// [`HostFunctionSpec::ALL`] then covers the whole ABI.
+fn call_for(op: HostFunctionSpec) -> Call {
+    let (import, call, operands) = match op {
+        HostFunctionSpec::GetLedgerSqn => (
+            import::LDGR_INDEX,
+            "(call $ldgr_index (i32.const 0) (i32.const 4))",
+            2,
+        ),
+        HostFunctionSpec::GetParentLedgerTime => (
+            import::PARENT_LDGR_TIME,
+            "(call $parent_ldgr_time (i32.const 0) (i32.const 4))",
+            2,
+        ),
+        HostFunctionSpec::GetParentLedgerHash => (
+            import::PARENT_LDGR_HASH,
+            "(call $parent_ldgr_hash (i32.const 0) (i32.const 32))",
+            2,
+        ),
+        HostFunctionSpec::GetBaseFee => (
+            import::BASE_FEE,
+            "(call $base_fee (i32.const 0) (i32.const 4))",
+            2,
+        ),
+        HostFunctionSpec::IsAmendmentEnabled => (
+            import::AMENDMENT_ENABLED,
+            "(call $amendment_enabled (i32.const 0) (i32.const 32))",
+            2,
+        ),
+        HostFunctionSpec::CacheLedgerObj => (
+            import::CACHE_LE,
+            "(call $cache_le (i32.const 0) (i32.const 32) (i32.const 0))",
+            3,
+        ),
+        HostFunctionSpec::GetTxField => (
+            import::TX_FIELD,
+            "(call $tx_field (i32.const 1) (i32.const 0) (i32.const 4))",
+            3,
+        ),
+        HostFunctionSpec::GetCurrentLedgerObjField => (
+            import::HOME_LE_FIELD,
+            "(call $home_le_field (i32.const 1) (i32.const 0) (i32.const 4))",
+            3,
+        ),
+        HostFunctionSpec::GetLedgerObjField => (
+            import::LE_FIELD,
+            "(call $le_field (i32.const 1) (i32.const 1) (i32.const 0) (i32.const 4))",
+            4,
+        ),
+        HostFunctionSpec::GetTxNestedField => (
+            import::TX_INNER,
+            "(call $tx_inner (i32.const 0) (i32.const 4) (i32.const 8) (i32.const 4))",
+            4,
+        ),
+        HostFunctionSpec::GetCurrentLedgerObjNestedField => (
+            import::HOME_LE_INNER,
+            "(call $home_le_inner (i32.const 0) (i32.const 4) (i32.const 8) (i32.const 4))",
+            4,
+        ),
+        HostFunctionSpec::GetLedgerObjNestedField => (
+            import::LE_INNER,
+            "(call $le_inner (i32.const 1) (i32.const 0) (i32.const 4) (i32.const 8) (i32.const 4))",
+            5,
+        ),
+        HostFunctionSpec::GetTxArrayLen => {
+            (import::TX_ARR_LEN, "(call $tx_arr_len (i32.const 1))", 1)
+        }
+        HostFunctionSpec::GetCurrentLedgerObjArrayLen => (
+            import::HOME_LE_ARR_LEN,
+            "(call $home_le_arr_len (i32.const 1))",
+            1,
+        ),
+        HostFunctionSpec::GetLedgerObjArrayLen => (
+            import::LE_ARR_LEN,
+            "(call $le_arr_len (i32.const 1) (i32.const 1))",
+            2,
+        ),
+        HostFunctionSpec::GetTxNestedArrayLen => (
+            import::TX_INNER_ARR_LEN,
+            "(call $tx_inner_arr_len (i32.const 0) (i32.const 4))",
+            2,
+        ),
+        HostFunctionSpec::GetCurrentLedgerObjNestedArrayLen => (
+            import::HOME_LE_INNER_ARR_LEN,
+            "(call $home_le_inner_arr_len (i32.const 0) (i32.const 4))",
+            2,
+        ),
+        HostFunctionSpec::GetLedgerObjNestedArrayLen => (
+            import::LE_INNER_ARR_LEN,
+            "(call $le_inner_arr_len (i32.const 1) (i32.const 0) (i32.const 4))",
+            3,
+        ),
+        HostFunctionSpec::CheckSignature => (
+            import::CHECK_SIG,
+            "(call $check_sig (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 0) (i32.const 0))",
+            6,
+        ),
+        HostFunctionSpec::AccountKeylet => (
+            import::ACCOUNTROOT_ID,
+            "(call $accountroot_id (i32.const 0) (i32.const 20) (i32.const 32) (i32.const 32))",
+            4,
+        ),
+        HostFunctionSpec::AmmKeylet => (
+            import::AMM_ID,
+            "(call $amm_id (i32.const 0) (i32.const 20) (i32.const 24) (i32.const 40) (i32.const 0) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::CheckKeylet => (
+            import::CHECK_ID,
+            "(call $check_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::CredentialKeylet => (
+            import::CREDENTIAL_ID,
+            "(call $credential_id (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 20) (i32.const 40) (i32.const 4) (i32.const 44) (i32.const 20))",
+            8,
+        ),
+        HostFunctionSpec::DelegateKeylet => (
+            import::DELEGATE_ID,
+            "(call $delegate_id (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 20) (i32.const 40) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::DepositPreauthKeylet => (
+            import::DEPOSIT_PREAUTH_ID,
+            "(call $deposit_preauth_id (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 20) (i32.const 40) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::DidKeylet => (
+            import::DID_ID,
+            "(call $did_id (i32.const 0) (i32.const 20) (i32.const 32) (i32.const 32))",
+            4,
+        ),
+        HostFunctionSpec::EscrowKeylet => (
+            import::ESCROW_ID,
+            "(call $escrow_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::TrustLineKeylet => (
+            import::TRUSTLINE_ID,
+            "(call $trustline_id (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 20) (i32.const 40) (i32.const 20) (i32.const 60) (i32.const 32))",
+            8,
+        ),
+        HostFunctionSpec::MptokenIssuanceKeylet => (
+            import::MPT_ISSUANCE_ID,
+            "(call $mpt_issuance_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::MptokenKeylet => (
+            import::MPTOKEN_ID,
+            "(call $mptoken_id (i32.const 0) (i32.const 24) (i32.const 24) (i32.const 20) (i32.const 44) (i32.const 20))",
+            6,
+        ),
+        HostFunctionSpec::NftokenOfferKeylet => (
+            import::NFT_OFFER_ID,
+            "(call $nft_offer_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::OfferKeylet => (
+            import::OFFER_ID,
+            "(call $offer_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::OracleKeylet => (
+            import::ORACLE_ID,
+            "(call $oracle_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::PaychannelKeylet => (
+            import::PAYCHAN_ID,
+            "(call $paychan_id (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 40) (i32.const 20))",
+            8,
+        ),
+        HostFunctionSpec::PermissionedDomainKeylet => (
+            import::PERMISSIONED_DOMAIN_ID,
+            "(call $permissioned_domain_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::SignerListKeylet => (
+            import::SIGNERS_ID,
+            "(call $signers_id (i32.const 0) (i32.const 20) (i32.const 32) (i32.const 32))",
+            4,
+        ),
+        HostFunctionSpec::TicketKeylet => (
+            import::TICKET_ID,
+            "(call $ticket_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::VaultKeylet => (
+            import::VAULT_ID,
+            "(call $vault_id (i32.const 0) (i32.const 20) (i32.const 0) (i32.const 4) (i32.const 32) (i32.const 32))",
+            6,
+        ),
+        HostFunctionSpec::Sha512Half => (
+            import::SHA512_HALF,
+            "(call $sha512_half (i32.const 0) (i32.const 4) (i32.const 0) (i32.const 32))",
+            4,
+        ),
+        HostFunctionSpec::Trace => (
+            import::TRACE,
+            "(call $trace (i32.const 0) (i32.const 0) (i32.const 1) (i32.const 0) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::UpdateData => (
+            import::SET_DATA,
+            "(call $set_data (i32.const 0) (i32.const 8))",
+            2,
+        ),
+        HostFunctionSpec::GetNft => (
+            import::NFT_URI,
+            "(call $nft_uri (i32.const 0) (i32.const 20) (i32.const 20) (i32.const 32) (i32.const 52) (i32.const 12))",
+            6,
+        ),
+        HostFunctionSpec::GetNftIssuer => (
+            import::NFT_ISSUER,
+            "(call $nft_issuer (i32.const 0) (i32.const 32) (i32.const 32) (i32.const 20))",
+            4,
+        ),
+        HostFunctionSpec::GetNftTaxon => (
+            import::NFT_TAXON,
+            "(call $nft_taxon (i32.const 0) (i32.const 32) (i32.const 32) (i32.const 4))",
+            4,
+        ),
+        HostFunctionSpec::GetNftFlags => (
+            import::NFT_FLAGS,
+            "(call $nft_flags (i32.const 0) (i32.const 32))",
+            2,
+        ),
+        HostFunctionSpec::GetNftTransferFee => (
+            import::NFT_XFER_FEE,
+            "(call $nft_xfer_fee (i32.const 0) (i32.const 32))",
+            2,
+        ),
+        HostFunctionSpec::GetNftSequence => (
+            import::NFT_SERIAL,
+            "(call $nft_serial (i32.const 0) (i32.const 32) (i32.const 32) (i32.const 4))",
+            4,
+        ),
+        HostFunctionSpec::FloatFromInt => (
+            import::FLOAT_FROM_INT,
+            "(call $float_from_int (i64.const 0) (i32.const 0) (i32.const 8) (i32.const 0))",
+            4,
+        ),
+        HostFunctionSpec::FloatFromUint => (
+            import::FLOAT_FROM_UINT,
+            "(call $float_from_uint (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::FloatFromStamount => (
+            import::FLOAT_FROM_STAMOUNT,
+            "(call $float_from_stamount (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::FloatFromStnumber => (
+            import::FLOAT_FROM_STNUMBER,
+            "(call $float_from_stnumber (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::FloatToInt => (
+            import::FLOAT_TO_INT,
+            "(call $float_to_int (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::FloatToMantExp => (
+            import::FLOAT_TO_MANT_EXP,
+            "(call $float_to_mant_exp (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 16) (i32.const 4))",
+            6,
+        ),
+        HostFunctionSpec::FloatFromMantExp => (
+            import::FLOAT_FROM_MANT_EXP,
+            "(call $float_from_mant_exp (i64.const 0) (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 0))",
+            5,
+        ),
+        HostFunctionSpec::FloatCompare => (
+            import::FLOAT_CMP,
+            "(call $float_cmp (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8))",
+            4,
+        ),
+        HostFunctionSpec::FloatAdd => (
+            import::FLOAT_ADD,
+            "(call $float_add (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 16) (i32.const 8) (i32.const 0))",
+            7,
+        ),
+        HostFunctionSpec::FloatSubtract => (
+            import::FLOAT_SUB,
+            "(call $float_sub (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 16) (i32.const 8) (i32.const 0))",
+            7,
+        ),
+        HostFunctionSpec::FloatMultiply => (
+            import::FLOAT_MULT,
+            "(call $float_mult (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 16) (i32.const 8) (i32.const 0))",
+            7,
+        ),
+        HostFunctionSpec::FloatDivide => (
+            import::FLOAT_DIV,
+            "(call $float_div (i32.const 0) (i32.const 8) (i32.const 8) (i32.const 8) (i32.const 16) (i32.const 8) (i32.const 0))",
+            7,
+        ),
+        HostFunctionSpec::FloatPower => (
+            import::FLOAT_POW,
+            "(call $float_pow (i32.const 0) (i32.const 8) (i32.const 2) (i32.const 8) (i32.const 8) (i32.const 0))",
+            6,
+        ),
+    };
+    Call {
+        import,
+        call,
+        operands,
+        yields: !matches!(op, HostFunctionSpec::Trace),
+    }
+}
+
+#[test]
+fn an_empty_module_burns_a_fixed_amount_of_fuel() {
+    let fuel = fuel_for("(i32.const 0)", &[ONE_PAGE], &FakeHost::new());
+    assert_eq!(fuel, EMPTY_MODULE_FUEL);
+}
+
+/// Calling a host function `n` times costs `n` times its gas, to the unit. Every
+/// other term is known — the module's floor, wasmi's fuel per call, one `drop` per
+/// answered call — so the total is a closed form, with the gas read from the spec
+/// table rather than restated. `n = 1` pins the charge, `n > 1` pins that it lands
+/// on every call rather than once per run.
+#[test]
+fn a_host_call_costs_its_gas_every_time_it_is_called() {
+    let host = FakeHost::new().answering_field(1, Answer::bytes([0xaa]));
+
+    for &op in HostFunctionSpec::ALL {
+        let call = call_for(op);
+        let per_call = wasmi_call_fuel(call.operands) + op.gas();
+
+        for n in 1..=3 {
+            let body = call.body(n);
+            let n = n as u64;
+
+            assert_eq!(
+                fuel_for(&body, &[call.import, ONE_PAGE], &host),
+                EMPTY_MODULE_FUEL + n * per_call + call.overhead(n),
+                "{n} x {}",
+                call.call
+            );
+        }
+    }
+}
+
+/// The gas charge precedes the call's body, so a failing call costs exactly what a
+/// successful one costs. Field 1 is answered and field 7 is not; the two modules
+/// are otherwise identical, so their totals are comparable.
+#[test]
+fn a_failing_host_call_costs_exactly_what_a_successful_one_costs() {
+    let host = FakeHost::new().answering_field(1, Answer::bytes([0xaa]));
+    let call = |field: i32| {
+        module(
+            &[import::HOME_LE_FIELD, ONE_PAGE],
+            &format!("(call $home_le_field (i32.const {field}) (i32.const 0) (i32.const 4))"),
+        )
+    };
+
+    let answered = run(&call(1), &host).expect("the module should run");
+    let refused = run(&call(7), &host).expect("the module should run");
+
+    assert_eq!(answered.result, 1);
+    assert_eq!(refused.result, code(HostError::FieldNotFound));
+    assert_eq!(refused.fuel_used, answered.fuel_used);
+}
+
+/// `fuel_used` is `gas - remaining`: what the run spent, not what was left or what
+/// it was handed. The gas figures are derived from the run's cost, so the boundary
+/// — exactly enough, and one short — is among the cases.
+#[test]
+fn fuel_used_is_what_was_spent_not_what_was_supplied() {
+    let host = FakeHost::new();
+    let op = HostFunctionSpec::GetLedgerSqn;
+    let call = call_for(op);
+    let wat = module(&[call.import, ONE_PAGE], call.call);
+    let cost = EMPTY_MODULE_FUEL + wasmi_call_fuel(call.operands) + op.gas();
+
+    // Exactly its cost is enough, and no amount above it changes the figure. The
+    // result is checked too, so the figure belongs to a run that did the work
+    // rather than to one that was cut short.
+    for gas in [cost, cost + 1, cost * 100, PLENTY_OF_GAS] {
+        let outcome = run_with_gas(&wat, gas, &host).expect("should run");
+        assert_eq!(
+            outcome.result, 4,
+            "gas {gas}: the call should have succeeded"
+        );
+        assert_eq!(outcome.fuel_used, cost, "gas {gas}");
+    }
+
+    // One fuel short: the run ends at the call it cannot pay for and still owes the
+    // whole limit, because `charge` spends what is left.
+    let short = run_with_gas(&wat, cost - 1, &host).expect_err("one fuel short must not complete");
+    assert!(
+        matches!(short.error, RunError::OutOfGas),
+        "expected the run to end out of gas, got: {short}"
+    );
+    assert_eq!(short.fuel_used, cost - 1);
+}
+
+/// Fuel is metered, so the same module burns the same fuel every time — a
+/// property consensus depends on.
+#[test]
+fn the_same_run_burns_the_same_fuel() {
+    let call = call_for(HostFunctionSpec::Trace);
+    let wat = module(&[call.import, ONE_PAGE], &call.body(1));
+
+    let first = run(&wat, &FakeHost::new()).expect("should run").fuel_used;
+    for _ in 0..4 {
+        assert_eq!(
+            run(&wat, &FakeHost::new()).expect("should run").fuel_used,
+            first
+        );
+    }
+    assert!(first > HostFunctionSpec::Trace.gas());
+}
+
+/// Too little gas to finish stops the run: the meter refuses the guest's own
+/// instructions before it ever reaches the host call.
+#[test]
+fn a_run_that_cannot_afford_itself_fails() {
+    let host = FakeHost::new();
+    let wat = module(
+        &[import::LDGR_INDEX, ONE_PAGE],
+        "(call $ldgr_index (i32.const 0) (i32.const 4))",
+    );
+
+    for gas in [0, 1, 10] {
+        let Err(failure) = run_with_gas(&wat, gas, &host) else {
+            panic!("gas {gas} should not have completed");
+        };
+        assert!(
+            matches!(failure.error, RunError::OutOfGas),
+            "gas {gas}: expected the run to end out of gas, got: {failure}"
+        );
+    }
+}
+
+/// A guest looping forever is stopped by gas rather than running away, and owes
+/// the gas it burned doing it.
+#[test]
+fn an_endless_loop_is_stopped_by_gas() {
+    const GAS: u64 = 100_000;
+
+    let host = FakeHost::new();
+    let wat = module(&[ONE_PAGE], "(loop $l (br $l)) (i32.const 0)");
+
+    let failure = run_with_gas(&wat, GAS, &host).expect_err("an endless loop must not complete");
+    assert!(
+        matches!(failure.error, RunError::OutOfGas),
+        "expected the meter to stop it, got: {failure}"
+    );
+    assert_eq!(
+        failure.fuel_used, GAS,
+        "a runaway guest burns the whole limit"
+    );
+}
+
+/// A host call refused its gas stops the run: the guest never gets a chance to
+/// ignore the refusal and carry on, and it is charged the whole limit.
+///
+/// The gas range is every amount that reaches the call and cannot pay for it, so
+/// the case is the whole boundary rather than one number. `trace` is the call under
+/// it because it is the one that could not report a refusal even if it wanted to:
+/// stopping the run is the whole of what the guest sees.
+#[test]
+fn a_host_call_refused_its_gas_stops_the_run() {
+    let host = FakeHost::new();
+    let op = HostFunctionSpec::Trace;
+    let call = call_for(op);
+    let wat = module(&[call.import, ONE_PAGE], &call.body(1));
+    // Measured rather than derived: the whole run's cost, less the call's own gas,
+    // is the least a guest can be given and still reach the call. Below that the
+    // meter stops the guest's own instructions instead, which is
+    // `a_run_that_cannot_afford_itself_fails`'s case, not this one.
+    let cost = run(&wat, &FakeHost::new())
+        .expect("the module should run")
+        .fuel_used;
+
+    for gas in cost - op.gas()..cost {
+        let Err(failure) = run_with_gas(&wat, gas, &host) else {
+            panic!("gas {gas}: the run completed, so the guest was handed the refusal");
+        };
+        assert!(
+            matches!(failure.error, RunError::OutOfGas),
+            "gas {gas}: expected the run to end out of gas, got: {failure}"
+        );
+        assert_eq!(
+            failure.fuel_used, gas,
+            "gas {gas}: a call it cannot afford burns the whole limit"
+        );
+    }
+    assert!(host.traces().is_empty(), "the host body must not have run");
+}
+
+// ---------------------------------------------------------------------------
+// The transfer limit
+// ---------------------------------------------------------------------------
+
+/// A module that repeats `call` while `keep_going` holds, then returns the last
+/// status, so a budget can be run to exhaustion inside one invocation.
+fn until_refused(imports: &str, call: &str, keep_going: &str) -> String {
+    module(
+        &[imports, ONE_PAGE],
+        &format!(
+            "(local $r i32)
+             (loop $l
+               (local.set $r {call})
+               (br_if $l {keep_going}))
+             (local.get $r)"
+        ),
+    )
+}
+
+/// For a call whose success is a positive byte count.
+const WHILE_POSITIVE: &str = "(i32.gt_s (local.get $r) (i32.const 0))";
+
+/// Bytes written into guest memory are charged against the run's budget, and the
+/// budget is a per-run total: 1 MiB of 1 KiB values exhausts it.
+#[test]
+fn writes_spend_the_transfer_budget() {
+    let host = FakeHost::new().answering_field(1, Answer::filler(MAX_FIELD_BYTES));
+    let wat = until_refused(
+        import::HOME_LE_FIELD,
+        &format!("(call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES}))"),
+        WHILE_POSITIVE,
+    );
+
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(outcome.result, code(HostError::OutOfTransferLimit));
+    assert_eq!(
+        host.fields_asked.borrow().len() as u64,
+        TRANSFER_LIMIT_BYTES / MAX_FIELD_BYTES as u64 + 1,
+        "one call per 1 KiB of budget, plus the one that was refused"
+    );
+}
+
+/// The budget is per run, not per call: a fresh run starts with a full budget.
+#[test]
+fn each_run_gets_its_own_budget() {
+    let wat = until_refused(
+        import::HOME_LE_FIELD,
+        &format!("(call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES}))"),
+        WHILE_POSITIVE,
+    );
+
+    for _ in 0..2 {
+        let host = FakeHost::new().answering_field(1, Answer::filler(MAX_FIELD_BYTES));
+        let outcome = run(&wat, &host).expect("the module should run");
+        assert_eq!(outcome.result, code(HostError::OutOfTransferLimit));
+        assert_eq!(
+            host.fields_asked.borrow().len() as u64,
+            TRANSFER_LIMIT_BYTES / MAX_FIELD_BYTES as u64 + 1
+        );
+    }
+}
+
+/// A run well inside the budget never sees it.
+#[test]
+fn a_modest_run_never_meets_the_budget() {
+    let host = FakeHost::new().answering_field(1, Answer::filler(MAX_FIELD_BYTES));
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        &format!("(call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES}))"),
+    );
+
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(outcome.result, MAX_FIELD_BYTES as i32);
+}
+
+/// A write the budget refuses is a write that did not happen. `float_to_mant_exp` is
+/// the case worth pinning: its two regions are charged as one, so a call that cannot
+/// pay for both must leave both alone rather than place the mantissa and refuse.
+#[test]
+fn a_write_the_budget_refuses_reaches_guest_memory_in_no_part() {
+    let host = FakeHost::new()
+        .answering_field(1, Answer::filler(MAX_FIELD_BYTES))
+        .answering_float_mant_exp(vec![1, 2, 3, 4, 5, 6, 7, 8], vec![9, 10, 11, 12]);
+
+    // Spend the budget on 1 KiB fields at offset 0, then ask for a mantissa and an
+    // exponent at offsets well clear of them.
+    let call = "(call $float_to_mant_exp (i32.const 0) (i32.const 8) (i32.const 2048) (i32.const 8) (i32.const 2064) (i32.const 4))";
+    let spent = |tail: &str| {
+        module(
+            &[import::HOME_LE_FIELD, import::FLOAT_TO_MANT_EXP, ONE_PAGE],
+            &format!(
+                "(local $r i32)
+                 (loop $l
+                   (local.set $r (call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES})))
+                   (br_if $l {WHILE_POSITIVE}))
+                 {tail}"
+            ),
+        )
+    };
+
+    let refused = run(&spent(call), &host).expect("the module should run");
+    assert_eq!(refused.result, code(HostError::OutOfTransferLimit));
+
+    let wat = spent(&format!(
+        "(drop {call})
+         (i32.or (i32.load8_u (i32.const 2048)) (i32.load8_u (i32.const 2064)))"
+    ));
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(outcome.result, 0, "neither region should be written");
+}
+
+/// The same rule on the path that writes straight into guest memory: `write_into`
+/// hands the host a slice *of the guest's own buffer*, so a value the budget cannot
+/// pay for has to be kept out of that slice before the host fills it.
+///
+/// The probe region is one the spending loop never writes to, so anything found there
+/// came from the refused call.
+#[test]
+fn a_straight_write_the_budget_refuses_reaches_guest_memory_in_no_part() {
+    /// Clear of the offset the spending loop writes to.
+    const PROBE: usize = 2048;
+    /// Every byte of the value, so the fold sees a prefix as readily as the whole.
+    const MARK: u8 = 0xff;
+
+    let host = FakeHost::new().answering_field(1, Answer::bytes(vec![MARK; MAX_FIELD_BYTES]));
+    let call = format!(
+        "(call $home_le_field (i32.const 1) (i32.const {PROBE}) (i32.const {MAX_FIELD_BYTES}))"
+    );
+
+    // Every local the tails below use is declared here: wasm wants them all ahead of
+    // the first instruction.
+    let spent = |tail: &str| {
+        module(
+            &[import::HOME_LE_FIELD, ONE_PAGE],
+            &format!(
+                "(local $r i32) (local $i i32) (local $seen i32)
+                 (loop $l
+                   (local.set $r (call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES})))
+                   (br_if $l {WHILE_POSITIVE}))
+                 {tail}"
+            ),
+        )
+    };
+
+    let refused = run(&spent(&call), &host).expect("the module should run");
+    assert_eq!(refused.result, code(HostError::OutOfTransferLimit));
+
+    // Guest memory starts zero-filled, so or-ing the region together reports whether
+    // any byte of it was written.
+    let wat = spent(&format!(
+        "(drop {call})
+         (loop $l
+           (local.set $seen (i32.or (local.get $seen)
+                                    (i32.load8_u (i32.add (i32.const {PROBE}) (local.get $i)))))
+           (local.set $i (i32.add (local.get $i) (i32.const 1)))
+           (br_if $l (i32.lt_u (local.get $i) (i32.const {MAX_FIELD_BYTES}))))
+         (local.get $seen)"
+    ));
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(outcome.result, 0, "not one byte should have been written");
+}
+
+/// What a write may deliver is what is *left* of the budget, to the byte.
+///
+/// The prologue spends all but `LEFT`, and field 3's host answers with as much as it
+/// is offered — so the window `write_into` opened is what it reports and what it
+/// leaves in guest memory, and both are read off as `LEFT`. A mark is a 1, so the
+/// fold over the probe's whole buffer counts the bytes that reached it.
+///
+/// `LEFT` is under [`MAX_FIELD_BYTES`] and the buffer is wider than both probes'
+/// values, so it is the budget answering and neither the field cap nor the guest's
+/// capacity. Field 4 is the byte past it: a host whose value is one larger than what
+/// is left, which no window can hold.
+#[test]
+fn a_write_may_deliver_what_is_left_of_the_budget_and_not_a_byte_more() {
+    /// Full-cap writes, all the prologue can make without overshooting.
+    const BULK: u64 = TRANSFER_LIMIT_BYTES / MAX_FIELD_BYTES as u64 - 1;
+    /// What the prologue leaves unspent.
+    const LEFT: usize = MAX_FIELD_BYTES / 2;
+    /// The write that trims what [`BULK`] leaves down to [`LEFT`].
+    const TRIM: usize = MAX_FIELD_BYTES - LEFT;
+    /// Clear of the offset the prologue writes to.
+    const PROBE: usize = 2048;
+    const BUFFER: usize = MAX_FIELD_BYTES;
+    /// One per byte written, so the fold below sums to how many there were.
+    const MARK: u8 = 1;
+
+    assert_eq!(
+        BULK * MAX_FIELD_BYTES as u64 + TRIM as u64 + LEFT as u64,
+        TRANSFER_LIMIT_BYTES,
+        "the prologue must spend all but LEFT of the budget"
+    );
+
+    let host = FakeHost::new()
+        .answering_field(1, Answer::filler(MAX_FIELD_BYTES))
+        .answering_field(2, Answer::filler(TRIM))
+        .answering_field(3, Answer::as_much_as_offered(MARK))
+        .answering_field(4, Answer::claiming(LEFT + 1));
+
+    let probe = |field: i32| {
+        format!(
+            "(call $home_le_field (i32.const {field}) (i32.const {PROBE}) (i32.const {BUFFER}))"
+        )
+    };
+    // Every local the tails use, declared where wasm wants them.
+    let after_prologue = |tail: String| {
+        let wat = module(
+            &[import::HOME_LE_FIELD, ONE_PAGE],
+            &format!(
+                "(local $i i32) (local $marks i32)
+                 (loop $l
+                   (drop (call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES})))
+                   (local.set $i (i32.add (local.get $i) (i32.const 1)))
+                   (br_if $l (i32.lt_u (local.get $i) (i32.const {BULK}))))
+                 (drop (call $home_le_field (i32.const 2) (i32.const 0) (i32.const {TRIM})))
+                 (local.set $i (i32.const 0))
+                 {tail}"
+            ),
+        );
+        run(&wat, &host).expect("the module should run").result
+    };
+
+    assert_eq!(
+        after_prologue(probe(3)),
+        LEFT as i32,
+        "the host should be offered exactly what is left"
+    );
+
+    // Guest memory starts zero-filled, so summing the probe's whole buffer counts the
+    // marks in it.
+    assert_eq!(
+        after_prologue(format!(
+            "(drop {})
+             (loop $l
+               (local.set $marks (i32.add (local.get $marks)
+                                          (i32.load8_u (i32.add (i32.const {PROBE}) (local.get $i)))))
+               (local.set $i (i32.add (local.get $i) (i32.const 1)))
+               (br_if $l (i32.lt_u (local.get $i) (i32.const {BUFFER}))))
+             (local.get $marks)",
+            probe(3)
+        )),
+        LEFT as i32,
+        "and that many marks, no more, should reach guest memory"
+    );
+
+    assert_eq!(
+        after_prologue(probe(4)),
+        code(HostError::OutOfTransferLimit),
+        "a value one byte past what is left fits no window"
+    );
+}
+
+/// Reads leave the budget alone: `read_borrowed` hands the host a slice *aliasing*
+/// guest memory, so there are no copied bytes to charge. What bounds how many reads
+/// a run can make is gas, which every host call pays before its body runs.
+///
+/// The observation is the write at the end, not the reads: the module reads four
+/// times the whole budget first, so a rule that charged reads would have nothing
+/// left, and the write would answer `OutOfTransferLimit` instead of a byte count.
+#[test]
+fn reads_do_not_spend_the_transfer_budget() {
+    /// 1 KiB reads, four times over the budget.
+    const READS: u64 = 4 * TRANSFER_LIMIT_BYTES / MAX_FIELD_BYTES as u64;
+
+    let host = FakeHost::new().answering_field(1, Answer::filler(MAX_FIELD_BYTES));
+    let read = trace_call(
+        TraceDataType::AsHex,
+        EMPTY_REGION,
+        &format!("(i32.const 0) (i32.const {MAX_FIELD_BYTES})"),
+    );
+    let wat = module(
+        &[import::TRACE, import::HOME_LE_FIELD, ONE_PAGE],
+        &format!(
+            "(local $i i32)
+             (loop $l
+               {read}
+               (local.set $i (i32.add (local.get $i) (i32.const 1)))
+               (br_if $l (i32.lt_u (local.get $i) (i32.const {READS}))))
+             (call $home_le_field (i32.const 1) (i32.const 0) (i32.const {MAX_FIELD_BYTES}))"
+        ),
+    );
+
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(
+        host.traces().len() as u64,
+        READS,
+        "every read should have been served"
+    );
+    assert_eq!(
+        outcome.result, MAX_FIELD_BYTES as i32,
+        "the write after {READS} reads of {MAX_FIELD_BYTES} bytes should still have its budget"
+    );
+}
+
+/// Only the output half of a read-write call spends the budget. `sha512_half`'s
+/// input is a borrowed read like any other, aliasing guest memory rather than
+/// crossing the boundary, so a run may hash far more bytes than the budget holds as
+/// long as the digests it writes fit inside it.
+///
+/// The two totals are asserted, so the arithmetic that makes the case is in the
+/// test rather than in a comment: the inputs alone would overrun the budget, the
+/// digests alone are a small fraction of it.
+#[test]
+fn only_the_output_half_of_a_read_write_spends_the_budget() {
+    /// Enough 1 KiB inputs to overrun the budget twice over.
+    const CALLS: u64 = 2 * TRANSFER_LIMIT_BYTES / MAX_FIELD_BYTES as u64;
+
+    assert!(
+        CALLS * MAX_FIELD_BYTES as u64 > TRANSFER_LIMIT_BYTES,
+        "the inputs alone must overrun the budget"
+    );
+    assert!(
+        CALLS * HASH_LEN as u64 <= TRANSFER_LIMIT_BYTES / 2,
+        "the digests alone must stay well inside it"
+    );
+
+    let host = FakeHost::new().answering_digest(Answer::filler(HASH_LEN));
+    let wat = module(
+        &[import::SHA512_HALF, ONE_PAGE],
+        &format!(
+            "(local $i i32)
+             (local $r i32)
+             (loop $l
+               (local.set $r (call $sha512_half (i32.const 0) (i32.const {MAX_FIELD_BYTES})
+                                                (i32.const 0) (i32.const {HASH_LEN})))
+               (local.set $i (i32.add (local.get $i) (i32.const 1)))
+               (br_if $l (i32.lt_u (local.get $i) (i32.const {CALLS}))))
+             (local.get $r)"
+        ),
+    );
+
+    let outcome = run(&wat, &host).expect("the module should run");
+    assert_eq!(
+        host.digested.borrow().len() as u64,
+        CALLS,
+        "every call should have been served"
+    );
+    assert_eq!(
+        outcome.result, HASH_LEN as i32,
+        "only the digests are charged, and they fit"
+    );
+}

crates/xrpl-wasm-vm/tests/memory_policy.rs

@@ -0,0 +1,621 @@
+//! The bounds, field-cap and buffer-fit rules `abi.rs` enforces on every region
+//! crossing the boundary. This is the policy the guest observes, so each rule is
+//! pinned to the code it answers with.
+
+mod support;
+
+use support::{
+    Answer, COMPLETED, EMPTY_REGION, FakeHost, ONE_PAGE, code, failure, import, module, status,
+    traced,
+};
+use xrpl_host_functions::{HASH_LEN, HostError, TraceDataType};
+use xrpl_wasm_vm::{MAX_FIELD_BYTES, RunError};
+
+/// One page, so anything at or past 65536 is out of bounds.
+const PAGE: i64 = 64 * 1024;
+
+/// The per-field size cap, as a wasm operand.
+const CAP: i64 = MAX_FIELD_BYTES as i64;
+/// One byte over the cap: the smallest value the engine must refuse.
+const OVER_CAP: i64 = CAP + 1;
+
+// ---------------------------------------------------------------------------
+// Output regions (`write_into`)
+// ---------------------------------------------------------------------------
+
+/// The whole output region must be in bounds, not merely its start — the engine
+/// checks `[dst, dst + cap)` before the host is allowed to write.
+#[test]
+fn an_output_region_running_past_memory_is_refused() {
+    let host = FakeHost::new();
+
+    for (dst, cap) in [(PAGE, 4), (PAGE - 3, 4), (PAGE + 1024, 4), (0, PAGE + 1)] {
+        let wat = module(
+            &[import::LDGR_INDEX, ONE_PAGE],
+            &format!("(call $ldgr_index (i32.const {dst}) (i32.const {cap}))"),
+        );
+        assert_eq!(
+            status(&wat, &host),
+            code(HostError::PointerOutOfBounds),
+            "dst {dst} cap {cap}"
+        );
+    }
+}
+
+/// A region ending exactly at the last byte of memory is in bounds.
+#[test]
+fn an_output_region_ending_at_the_last_byte_is_allowed() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::LDGR_INDEX, ONE_PAGE],
+        &format!("(call $ldgr_index (i32.const {}) (i32.const 4))", PAGE - 4),
+    );
+    assert_eq!(status(&wat, &host), 4);
+}
+
+/// The wire carries `i32`, so a guest can present a negative pointer or length.
+#[test]
+fn a_negative_output_pointer_or_length_is_refused() {
+    let host = FakeHost::new();
+
+    for (dst, cap) in [(-1, 4), (0, -1), (-1, -1), (i32::MIN, 4)] {
+        let wat = module(
+            &[import::LDGR_INDEX, ONE_PAGE],
+            &format!("(call $ldgr_index (i32.const {dst}) (i32.const {cap}))"),
+        );
+        assert_eq!(
+            status(&wat, &host),
+            code(HostError::InvalidParams),
+            "dst {dst} cap {cap}"
+        );
+    }
+}
+
+/// The host reports a value's true length whether or not it fitted; a value that
+/// did not fit is the guest's error, not the host's.
+#[test]
+fn a_value_larger_than_the_buffer_is_refused() {
+    let host = FakeHost::new().answering_field(1, Answer::filler(64));
+
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        "(call $home_le_field (i32.const 1) (i32.const 0) (i32.const 63))",
+    );
+    assert_eq!(status(&wat, &host), code(HostError::BufferTooSmall));
+
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        "(call $home_le_field (i32.const 1) (i32.const 0) (i32.const 64))",
+    );
+    assert_eq!(status(&wat, &host), 64, "exactly enough room is enough");
+}
+
+/// A zero-length output region is in bounds and simply cannot hold anything.
+#[test]
+fn a_zero_length_output_region_is_in_bounds_but_too_small() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::LDGR_INDEX, ONE_PAGE],
+        "(call $ldgr_index (i32.const 0) (i32.const 0))",
+    );
+    assert_eq!(status(&wat, &host), code(HostError::BufferTooSmall));
+}
+
+/// A host that reports more than the per-field cap is refused even when the
+/// guest offered room for it: the cap is the engine's rule, not the buffer's.
+#[test]
+fn a_value_past_the_field_cap_is_refused() {
+    let host = FakeHost::new()
+        .answering_field(1, Answer::claiming(OVER_CAP as usize))
+        .answering_field(2, Answer::claiming(MAX_FIELD_BYTES));
+
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        "(call $home_le_field (i32.const 1) (i32.const 0) (i32.const 4096))",
+    );
+    assert_eq!(status(&wat, &host), code(HostError::DataFieldTooLarge));
+
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        "(call $home_le_field (i32.const 2) (i32.const 0) (i32.const 4096))",
+    );
+    assert_eq!(status(&wat, &host), CAP as i32, "the cap itself is allowed");
+}
+
+/// A refused over-cap value leaves nothing behind. `write_into` hands the host at
+/// most [`MAX_FIELD_BYTES`] of the guest's buffer however much room the guest
+/// declared, so a value past the cap does not fit the region it is offered and no
+/// prefix of it can reach guest memory either.
+///
+/// The host answers with a real over-cap value: [`Answer::claiming`] writes
+/// nothing whatever the engine does, so it could not tell the two apart. The
+/// second module folds the *whole* declared buffer rather than one byte, so the
+/// claim is about the region and not about its first byte.
+#[test]
+fn an_over_cap_value_is_refused_without_reaching_guest_memory() {
+    /// The buffer the guest declares: well over the cap, so the clamp bites.
+    const BUFFER: usize = 4096;
+
+    let over_cap = vec![0xff; MAX_FIELD_BYTES + 1];
+    let host = FakeHost::new().answering_field(1, Answer::bytes(over_cap));
+    let call = format!("(call $home_le_field (i32.const 1) (i32.const 0) (i32.const {BUFFER}))");
+
+    // The status the guest sees, from a module that returns it directly.
+    let refusing = module(&[import::HOME_LE_FIELD, ONE_PAGE], &call);
+    assert_eq!(
+        status(&refusing, &host),
+        code(HostError::DataFieldTooLarge),
+        "the value is refused"
+    );
+
+    // Every byte of the buffer, or-ed together: guest memory starts zero-filled,
+    // so any byte the host wrote shows up here.
+    let reading = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        &format!(
+            "(local $i i32)
+             (local $seen i32)
+             (drop {call})
+             (loop $l
+               (local.set $seen (i32.or (local.get $seen) (i32.load8_u (local.get $i))))
+               (local.set $i (i32.add (local.get $i) (i32.const 1)))
+               (br_if $l (i32.lt_u (local.get $i) (i32.const {BUFFER}))))
+             (local.get $seen)"
+        ),
+    );
+    assert_eq!(
+        status(&reading, &host),
+        0,
+        "and not one of its bytes is in the guest's buffer"
+    );
+}
+
+/// The field cap is checked before the buffer-fit rule, so a value that breaks both
+/// is reported as over-cap. The guest branches on the code, and the two rules
+/// answer different questions, so the order is worth pinning.
+#[test]
+fn the_field_cap_precedes_the_buffer_fit_check() {
+    let host = FakeHost::new().answering_field(1, Answer::claiming(MAX_FIELD_BYTES + 1));
+
+    // A 63-byte buffer: the value is both over the cap and far too big to fit.
+    let wat = module(
+        &[import::HOME_LE_FIELD, ONE_PAGE],
+        "(call $home_le_field (i32.const 1) (i32.const 0) (i32.const 63))",
+    );
+    assert_eq!(status(&wat, &host), code(HostError::DataFieldTooLarge));
+}
+
+// ---------------------------------------------------------------------------
+// Input regions (`Region::read`, via `sha512_half`)
+//
+// `sha512_half`'s first pair is an input region like any other, and it is the
+// input the guest gets a status back from: `trace`, the other reader, answers
+// nothing at all. So the codes are pinned here and the silence below.
+// ---------------------------------------------------------------------------
+
+/// An input region is bounds-checked the same way an output region is. Every case
+/// here stays within the field cap, which on an input is checked first.
+#[test]
+fn an_input_region_running_past_memory_is_refused() {
+    let host = FakeHost::new();
+
+    for (ptr, len) in [(PAGE, 1), (PAGE - 3, 4), (PAGE - 1, CAP)] {
+        let wat = module(
+            &[import::SHA512_HALF, ONE_PAGE],
+            &format!(
+                "(call $sha512_half (i32.const {ptr}) (i32.const {len})
+                                    (i32.const 0) (i32.const {HASH_LEN}))"
+            ),
+        );
+        assert_eq!(
+            status(&wat, &host),
+            code(HostError::PointerOutOfBounds),
+            "ptr {ptr} len {len}"
+        );
+        assert!(host.digested.borrow().is_empty(), "the host is not called");
+    }
+}
+
+#[test]
+fn a_negative_input_pointer_or_length_is_refused() {
+    let host = FakeHost::new();
+
+    for (ptr, len) in [(-1, 1), (0, -1), (i32::MIN, 1)] {
+        let wat = module(
+            &[import::SHA512_HALF, ONE_PAGE],
+            &format!(
+                "(call $sha512_half (i32.const {ptr}) (i32.const {len})
+                                    (i32.const 0) (i32.const {HASH_LEN}))"
+            ),
+        );
+        assert_eq!(
+            status(&wat, &host),
+            code(HostError::InvalidParams),
+            "ptr {ptr} len {len}"
+        );
+    }
+}
+
+/// The field cap bounds what the guest may hand *in*, too.
+#[test]
+fn an_input_past_the_field_cap_is_refused() {
+    let host = FakeHost::new();
+    let digest = |len: i64| {
+        module(
+            &[import::SHA512_HALF, ONE_PAGE],
+            &format!(
+                "(call $sha512_half (i32.const 0) (i32.const {len})
+                                    (i32.const 2048) (i32.const {HASH_LEN}))"
+            ),
+        )
+    };
+
+    assert_eq!(
+        status(&digest(OVER_CAP), &host),
+        code(HostError::DataFieldTooLarge)
+    );
+    assert!(host.digested.borrow().is_empty());
+
+    assert_eq!(
+        status(&digest(CAP), &host),
+        HASH_LEN as i32,
+        "the cap itself is allowed"
+    );
+}
+
+/// The two directions check in opposite orders: an input's length is known before
+/// the read, so the cap comes first, while an output's region has to be resolved
+/// before the host can produce a value, so bounds come first there.
+#[test]
+fn the_field_cap_precedes_the_bounds_check_on_an_input() {
+    let host = FakeHost::new();
+
+    let reading = module(
+        &[import::SHA512_HALF, ONE_PAGE],
+        &format!(
+            "(call $sha512_half (i32.const 0) (i32.const {})
+                                (i32.const 0) (i32.const {HASH_LEN}))",
+            PAGE + 1
+        ),
+    );
+    assert_eq!(status(&reading, &host), code(HostError::DataFieldTooLarge));
+
+    let writing = module(
+        &[import::LDGR_INDEX, ONE_PAGE],
+        &format!("(call $ldgr_index (i32.const 0) (i32.const {}))", PAGE + 1),
+    );
+    assert_eq!(status(&writing, &host), code(HostError::PointerOutOfBounds));
+}
+
+// ---------------------------------------------------------------------------
+// The reader with no result (`read_borrowed`, via `trace`)
+// ---------------------------------------------------------------------------
+
+/// `trace` reads two regions and either one being bad refuses the call. The same
+/// rule as above, and the guest is told nothing: the refusal is the host not being
+/// called, and the run carries on to the constant that follows.
+#[test]
+fn both_of_traces_regions_are_checked_silently() {
+    let host = FakeHost::new();
+    let regions = [
+        (
+            format!("(i32.const {PAGE}) (i32.const 1)"),
+            EMPTY_REGION.to_owned(),
+        ),
+        (
+            EMPTY_REGION.to_owned(),
+            format!("(i32.const {PAGE}) (i32.const 1)"),
+        ),
+        (
+            EMPTY_REGION.to_owned(),
+            format!("(i32.const 0) (i32.const {OVER_CAP})"),
+        ),
+        (
+            "(i32.const -1) (i32.const 1)".to_owned(),
+            EMPTY_REGION.to_owned(),
+        ),
+    ];
+
+    for (msg, data) in regions {
+        let wat = module(
+            &[import::TRACE, ONE_PAGE],
+            &traced(TraceDataType::AsHex, &msg, &data),
+        );
+        assert_eq!(status(&wat, &host), COMPLETED, "msg {msg} data {data}");
+        assert!(
+            host.traces().is_empty(),
+            "msg {msg} data {data}: the host must not be called"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Both at once (`write_buffered`, via `sha512_half`)
+// ---------------------------------------------------------------------------
+
+/// A call with an input and an output region decides everything about the input
+/// before anything about the output, so a bad input is reported however the output
+/// region is wrong — out of bounds, or a pointer that is not one at all.
+///
+/// The whole output region, params included, is judged after the host has answered.
+/// Hoisting any part of that above the call would put the output's verdict first for
+/// these cases, and there is no half of it that can be hoisted on a principle the
+/// other half shares.
+#[test]
+fn a_read_write_checks_its_input_before_its_output() {
+    let host = FakeHost::new();
+    let digest = |src: i64, src_len: i64, dst: i64| {
+        module(
+            &[import::SHA512_HALF, ONE_PAGE],
+            &format!(
+                "(call $sha512_half (i32.const {src}) (i32.const {src_len})
+                                    (i32.const {dst}) (i32.const {HASH_LEN}))"
+            ),
+        )
+    };
+
+    let over_cap = digest(0, OVER_CAP, 0);
+    assert_eq!(status(&over_cap, &host), code(HostError::DataFieldTooLarge));
+
+    let out_of_bounds = digest(PAGE, 4, 0);
+    assert_eq!(
+        status(&out_of_bounds, &host),
+        code(HostError::PointerOutOfBounds)
+    );
+
+    // A bad input against each way the output can be wrong: the input's verdict is
+    // the one reported, and the host is never asked for a value nobody can take.
+    for dst in [PAGE, -1] {
+        let both_bad = digest(0, OVER_CAP, dst);
+        assert_eq!(
+            status(&both_bad, &host),
+            code(HostError::DataFieldTooLarge),
+            "dst {dst}"
+        );
+    }
+    assert!(host.digested.borrow().is_empty(), "the host is not reached");
+}
+
+/// The output half of a read-write call obeys the same rules as a plain write.
+#[test]
+fn a_read_write_output_obeys_the_write_rules() {
+    let host = FakeHost::new().answering_digest(Answer::filler(32));
+
+    let wat = module(
+        &[import::SHA512_HALF, ONE_PAGE],
+        "(call $sha512_half (i32.const 0) (i32.const 4) (i32.const 0) (i32.const 31))",
+    );
+    assert_eq!(status(&wat, &host), code(HostError::BufferTooSmall));
+
+    let wat = module(
+        &[import::SHA512_HALF, ONE_PAGE],
+        &format!(
+            "(call $sha512_half (i32.const 0) (i32.const 4) (i32.const {PAGE}) (i32.const 32))"
+        ),
+    );
+    assert_eq!(status(&wat, &host), code(HostError::PointerOutOfBounds));
+}
+
+/// A refused value reaches guest memory in no part, however much of it the host
+/// wrote. The host answers with 32 bytes it did write and a length it did not, so
+/// the refusal happens with the value sitting in the run's output buffer — and the
+/// guest's buffer has to come back untouched.
+///
+/// Stronger than the contract asks for: a guest must not read its buffer on a
+/// negative status. It holds because the buffer is copied to the guest only after
+/// the length, the bounds, the fit and the budget have all passed, so there is no
+/// window in which a refused value is in guest memory.
+#[test]
+fn a_refused_value_leaves_nothing_in_guest_memory() {
+    const MARKER: u8 = 77;
+
+    // The two refusals a value can meet after the host has produced it: longer
+    // than the field cap, and longer than the buffer the guest offered.
+    let refusals = [
+        (MAX_FIELD_BYTES + 1, HASH_LEN, HostError::DataFieldTooLarge),
+        (HASH_LEN, HASH_LEN - 1, HostError::BufferTooSmall),
+    ];
+
+    for (claimed, cap, expected) in refusals {
+        let host =
+            FakeHost::new().answering_digest(Answer::writing_but_claiming([MARKER; 32], claimed));
+        let call = format!(
+            "(call $sha512_half (i32.const 0) (i32.const 4) (i32.const 64) (i32.const {cap}))"
+        );
+
+        let refused = module(&[import::SHA512_HALF, ONE_PAGE], &call);
+        assert_eq!(
+            status(&refused, &host),
+            code(expected),
+            "claiming {claimed}"
+        );
+
+        // The same call, reporting what is at the output region afterwards.
+        let inspect = module(
+            &[import::SHA512_HALF, ONE_PAGE],
+            &format!("(drop {call}) (i32.load8_u (i32.const 64))"),
+        );
+        assert_eq!(
+            status(&inspect, &host),
+            0,
+            "claiming {claimed}: the refused value must not have been written"
+        );
+    }
+}
+
+/// An input region may overlap the output region: the host is served the input as
+/// it stands and its answer lands afterwards, so the two cannot interfere. The
+/// marker is any byte distinct from the input's first (`a`), so `finish` returning
+/// it proves the write landed.
+#[test]
+fn an_input_may_overlap_the_output() {
+    const MARKER: u8 = 99;
+
+    let host = FakeHost::new().answering_digest(Answer::bytes([MARKER; HASH_LEN]));
+
+    let wat = module(
+        &[
+            import::SHA512_HALF,
+            ONE_PAGE,
+            r#"(data (i32.const 0) "abcd")"#,
+        ],
+        &format!(
+            "(drop (call $sha512_half (i32.const 0) (i32.const 4)
+                                      (i32.const 0) (i32.const {HASH_LEN})))
+             (i32.load8_u (i32.const 0))"
+        ),
+    );
+    assert_eq!(
+        status(&wat, &host),
+        i32::from(MARKER),
+        "the output overwrote the input"
+    );
+    assert_eq!(
+        *host.digested.borrow(),
+        vec![b"abcd".to_vec()],
+        "the host saw the input as it was"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// The memory export itself
+// ---------------------------------------------------------------------------
+
+/// A host call with no memory to work in ends the run instead of answering the
+/// guest: there is no buffer for a status to describe, and nothing the guest could
+/// do about the answer — which is what puts this beside out-of-gas on the fatal
+/// channel. What the guest burned getting there is still charged.
+fn assert_no_memory(wat: &str, host: &FakeHost) {
+    let failure = failure(wat, host);
+    assert!(
+        matches!(failure.error, RunError::NoMemory),
+        "expected the run to end for want of a memory export, got: {failure}"
+    );
+    assert!(failure.fuel_used > 0, "{failure}");
+}
+
+/// Every region is relative to the guest's exported memory, so a module without
+/// one cannot make a host call at all.
+#[test]
+fn a_module_that_exports_no_memory_cannot_call_the_host() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::LDGR_INDEX, "(memory 1)"],
+        "(call $ldgr_index (i32.const 0) (i32.const 4))",
+    );
+    assert_no_memory(&wat, &host);
+}
+
+/// Having no memory is answered before anything about a call's arguments, so a
+/// module without one ends the run even when its arguments would have earned a
+/// guest-visible code of their own (here an input over the field cap).
+///
+/// The order is deliberate: no memory is a fact about the instance, not about this
+/// call, and a region cannot be validated against a memory that is not there. It
+/// costs the guest nothing — every call such a module makes ends the run anyway.
+#[test]
+fn no_memory_is_answered_before_a_calls_arguments_are() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::SHA512_HALF, "(memory 1)"],
+        &format!(
+            "(call $sha512_half (i32.const 0) (i32.const {OVER_CAP})
+                                (i32.const 0) (i32.const {HASH_LEN}))"
+        ),
+    );
+    assert_no_memory(&wat, &host);
+}
+
+/// The memory's export *name* is not part of the contract: the engine takes the
+/// module's memory whatever it is called. Nothing in the wasm spec attaches meaning
+/// to `"memory"` — it is a toolchain convention, so the kind decides.
+#[test]
+fn a_memory_exported_under_any_name_is_the_guests_memory() {
+    let host = FakeHost::new();
+
+    for name in ["mem", "linear", "the memory"] {
+        let wat = module(
+            &[
+                import::LDGR_INDEX,
+                &format!(r#"(memory (export "{name}") 1)"#),
+            ],
+            "(drop (call $ldgr_index (i32.const 64) (i32.const 4)))
+             (i32.load (i32.const 64))",
+        );
+        assert_eq!(
+            status(&wat, &host),
+            7,
+            "the host wrote into the memory exported as '{name}'"
+        );
+    }
+}
+
+/// One memory exported under several names is one memory. The engine resolves the
+/// first export of kind memory, and with at most one memory per module every such
+/// export is that memory, so the order the exports are walked in cannot change the
+/// answer.
+#[test]
+fn one_memory_exported_under_several_names_is_still_that_memory() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[
+            import::LDGR_INDEX,
+            r#"(memory (export "memory") (export "mem") (export "linear") 1)"#,
+        ],
+        "(drop (call $ldgr_index (i32.const 64) (i32.const 4)))
+         (i32.load (i32.const 64))",
+    );
+    assert_eq!(status(&wat, &host), 7);
+}
+
+/// The export has to *be* a memory: a global named `memory` is not one, and it
+/// neither serves as the guest's memory nor hides the memory the module really
+/// exports. The kind decides, so the conventional name carries no weight on
+/// either side.
+#[test]
+fn an_export_named_memory_that_is_not_a_memory_is_not_the_guests_memory() {
+    let host = FakeHost::new();
+
+    let call = "(call $ldgr_index (i32.const 0) (i32.const 4))";
+
+    let wrong_kind = module(
+        &[
+            import::LDGR_INDEX,
+            "(memory 1)",
+            r#"(global (export "memory") i32 (i32.const 0))"#,
+        ],
+        call,
+    );
+    assert_no_memory(&wrong_kind, &host);
+
+    let shadowed = module(
+        &[
+            import::LDGR_INDEX,
+            r#"(memory (export "mem") 1)"#,
+            r#"(global (export "memory") i32 (i32.const 0))"#,
+        ],
+        call,
+    );
+    assert_eq!(
+        status(&shadowed, &host),
+        4,
+        "the real memory is found past the global that took its name"
+    );
+}
+
+/// Bounds follow the memory the module actually declared, not a fixed page.
+#[test]
+fn bounds_follow_the_declared_memory_size() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::LDGR_INDEX, r#"(memory (export "memory") 2)"#],
+        &format!("(call $ldgr_index (i32.const {PAGE}) (i32.const 4))"),
+    );
+    assert_eq!(status(&wat, &host), 4, "the second page is in bounds");
+}

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

@@ -0,0 +1,591 @@
+//! What screening refuses, and that it refuses nothing a run would have served.
+//!
+//! `check` reaches its verdict from the compiled module alone, so these tests take
+//! no host — except the ones that put the same module through `run` to compare the
+//! two.
+
+mod support;
+
+use support::{ENTRY, FakeHost, ONE_PAGE, PLENTY_OF_GAS, assemble, import, module};
+use xrpl_host_functions::HostFunctionSpec;
+use xrpl_wasm_vm::{CheckError, MAX_MEMORY_PAGES, MAX_TABLE_ELEMENTS, RunError};
+
+/// Assert which stage screening refused a module at, because the caller maps the
+/// stages separately. The error comes back out for the tests that also read its
+/// message.
+macro_rules! assert_stage {
+    ($refusal:expr, $stage:pat) => {{
+        let refusal = $refusal;
+        assert!(
+            matches!(refusal, $stage),
+            concat!("expected a ", stringify!($stage), " refusal, got: {}"),
+            refusal
+        );
+        refusal
+    }};
+}
+
+/// Screens `wat`, which must assemble.
+fn check(wat: &str) -> Result<(), CheckError> {
+    xrpl_wasm_vm::check(&assemble(wat), ENTRY)
+}
+
+fn refusal(wat: &str) -> CheckError {
+    check(wat).expect_err(&format!("expected this module to be refused:\n{wat}"))
+}
+
+fn passes(wat: &str) {
+    if let Err(refusal) = check(wat) {
+        panic!("expected this module to pass, but: {refusal}\n{wat}");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Compiling
+// ---------------------------------------------------------------------------
+
+/// A contract that imports a host function, exports its memory and exports the
+/// entry point is what screening is looking for.
+#[test]
+fn a_runnable_contract_passes() {
+    passes(&module(
+        &[import::LDGR_INDEX, ONE_PAGE],
+        "(call $ldgr_index (i32.const 0) (i32.const 4))",
+    ));
+}
+
+/// Bytes that are not a wasm module at all.
+#[test]
+fn garbage_does_not_pass() {
+    for bytes in [b"".as_slice(), b"not wasm", &[0x00, 0x61, 0x73, 0x6d]] {
+        let refusal = xrpl_wasm_vm::check(bytes, ENTRY).expect_err("garbage must not pass");
+        assert_stage!(refusal, CheckError::Compile(_));
+    }
+}
+
+/// Screening takes wasm binaries, and text is not one — the same rule the VM
+/// applies, from the same `wasmi` built without its `wat` feature. Turning that
+/// feature on would make this transaction blob valid at both ends.
+#[test]
+fn a_text_format_module_does_not_pass() {
+    let text = module(&[ONE_PAGE], "(i32.const 0)");
+
+    let refusal =
+        xrpl_wasm_vm::check(text.as_bytes(), ENTRY).expect_err("text must not pass as a module");
+    assert_stage!(refusal, CheckError::Compile(_));
+
+    // The same module, assembled first, passes: the text is sound and only the
+    // format was refused.
+    passes(&text);
+}
+
+/// A feature the engine disables is refused here too, because both stages compile
+/// against the one engine. `vm_limits.rs` walks every disabled feature; this pins
+/// that screening sees the same configuration.
+#[test]
+fn a_disabled_feature_does_not_pass() {
+    let refusal = refusal(&module(
+        &[ONE_PAGE],
+        "(drop (f64.add (f64.const 1) (f64.const 2))) (i32.const 0)",
+    ));
+    let refusal = assert_stage!(refusal, CheckError::Compile(_)).to_string();
+    assert!(refusal.contains("floating-point"), "{refusal}");
+}
+
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+
+/// Every host function the ABI declares, spelled as a guest imports it. The count
+/// is asserted against the ABI so a function added to it cannot be left out here.
+const ALL_IMPORTS: [&str; 61] = [
+    import::LDGR_INDEX,
+    import::PARENT_LDGR_TIME,
+    import::PARENT_LDGR_HASH,
+    import::BASE_FEE,
+    import::AMENDMENT_ENABLED,
+    import::CACHE_LE,
+    import::TX_FIELD,
+    import::HOME_LE_FIELD,
+    import::LE_FIELD,
+    import::TX_INNER,
+    import::HOME_LE_INNER,
+    import::LE_INNER,
+    import::TX_ARR_LEN,
+    import::HOME_LE_ARR_LEN,
+    import::LE_ARR_LEN,
+    import::TX_INNER_ARR_LEN,
+    import::HOME_LE_INNER_ARR_LEN,
+    import::LE_INNER_ARR_LEN,
+    import::CHECK_SIG,
+    import::ACCOUNTROOT_ID,
+    import::AMM_ID,
+    import::CHECK_ID,
+    import::CREDENTIAL_ID,
+    import::DELEGATE_ID,
+    import::DEPOSIT_PREAUTH_ID,
+    import::DID_ID,
+    import::ESCROW_ID,
+    import::TRUSTLINE_ID,
+    import::MPT_ISSUANCE_ID,
+    import::MPTOKEN_ID,
+    import::NFT_OFFER_ID,
+    import::OFFER_ID,
+    import::ORACLE_ID,
+    import::PAYCHAN_ID,
+    import::PERMISSIONED_DOMAIN_ID,
+    import::SIGNERS_ID,
+    import::TICKET_ID,
+    import::VAULT_ID,
+    import::SHA512_HALF,
+    import::TRACE,
+    import::SET_DATA,
+    import::NFT_URI,
+    import::NFT_ISSUER,
+    import::NFT_TAXON,
+    import::NFT_FLAGS,
+    import::NFT_XFER_FEE,
+    import::NFT_SERIAL,
+    import::FLOAT_FROM_INT,
+    import::FLOAT_FROM_UINT,
+    import::FLOAT_FROM_STAMOUNT,
+    import::FLOAT_FROM_STNUMBER,
+    import::FLOAT_TO_INT,
+    import::FLOAT_TO_MANT_EXP,
+    import::FLOAT_FROM_MANT_EXP,
+    import::FLOAT_CMP,
+    import::FLOAT_ADD,
+    import::FLOAT_SUB,
+    import::FLOAT_MULT,
+    import::FLOAT_DIV,
+    import::FLOAT_POW,
+];
+
+#[test]
+fn every_declared_host_function_may_be_imported() {
+    assert_eq!(
+        ALL_IMPORTS.len(),
+        HostFunctionSpec::ALL.len(),
+        "the ABI gained a host function with no import declaration in this test"
+    );
+
+    let mut parts = ALL_IMPORTS.to_vec();
+    parts.push(ONE_PAGE);
+    passes(&module(&parts, "(i32.const 0)"));
+}
+
+/// A module may import fewer host functions than are registered, but not more.
+#[test]
+fn an_unknown_host_function_does_not_pass() {
+    let refusal = refusal(&module(
+        &[
+            r#"(import "host_lib" "no_such_function" (func $f (param i32) (result i32)))"#,
+            ONE_PAGE,
+        ],
+        "(call $f (i32.const 0))",
+    ));
+    let refusal = assert_stage!(refusal, CheckError::Import(_)).to_string();
+    assert!(
+        refusal.contains("no host function 'no_such_function'"),
+        "{refusal}"
+    );
+}
+
+/// Host functions live under one module name — `host_lib` — and an import naming
+/// another is refused even when the function name is real. `env` is in the list
+/// because that is what plain clang emits.
+#[test]
+fn an_import_from_another_module_does_not_pass() {
+    for module_name in ["host", "env", ""] {
+        let refusal = refusal(&module(
+            &[
+                &format!(
+                    r#"(import "{module_name}" "ldgr_index" (func $f (param i32 i32) (result i32)))"#
+                ),
+                ONE_PAGE,
+            ],
+            "(call $f (i32.const 0) (i32.const 4))",
+        ));
+        let refusal = assert_stage!(refusal, CheckError::Import(_)).to_string();
+        assert!(refusal.contains("is not from 'host_lib'"), "{refusal}");
+    }
+}
+
+/// A host function's name imported as something other than a function. The engine
+/// defines it as a function and nothing else, so this does not link either.
+#[test]
+fn a_host_function_imported_as_a_global_does_not_pass() {
+    let refusal = refusal(&module(
+        &[
+            r#"(import "host_lib" "ldgr_index" (global $g i32))"#,
+            ONE_PAGE,
+        ],
+        "(global.get $g)",
+    ));
+    let refusal = assert_stage!(refusal, CheckError::Import(_)).to_string();
+    assert!(
+        refusal.contains("'host_lib::ldgr_index' is not a function"),
+        "{refusal}"
+    );
+}
+
+/// A module faulty at two stages is refused by the earlier one — it imports what no
+/// engine serves *and* exports no entry point. The imports are what the rest of the
+/// module depends on, so that is the message worth having.
+#[test]
+fn the_earlier_stage_is_the_one_reported() {
+    let refusal = refusal(
+        r#"(module
+             (import "host_lib" "no_such_function" (func $f (result i32)))
+             (memory (export "memory") 1)
+             (func (export "not_the_entry_point") (result i32) (call $f)))"#,
+    );
+
+    assert_stage!(refusal, CheckError::Import(_));
+}
+
+/// The signature is the one part of an import screening does not compare, so a
+/// module that will not link can still pass. Recorded here because it is the gap
+/// this stage leaves, not because it is wanted.
+#[test]
+fn an_import_with_the_wrong_signature_still_passes() {
+    let wat = module(
+        &[
+            r#"(import "host_lib" "ldgr_index" (func $f (param i64 i64) (result i32)))"#,
+            ONE_PAGE,
+        ],
+        "(i32.const 0)",
+    );
+    passes(&wat);
+
+    let host = FakeHost::new();
+    let failure = xrpl_wasm_vm::run(&assemble(&wat), PLENTY_OF_GAS, &host, ENTRY)
+        .expect_err("a mistyped import must not link");
+    assert!(
+        matches!(failure.error, RunError::Instantiate(_)),
+        "{failure}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// The entry point
+// ---------------------------------------------------------------------------
+
+#[test]
+fn a_missing_entry_point_does_not_pass() {
+    let refusal = refusal(
+        r#"(module (memory (export "memory") 1)
+                              (func (export "other") (result i32) (i32.const 0)))"#,
+    );
+    let refusal = assert_stage!(refusal, CheckError::EntryPoint(_)).to_string();
+    assert_eq!(refusal, "no entry point 'finish'");
+}
+
+/// The entry point is looked up by the name the caller asks for, as a run looks it
+/// up: screening a contract for one entry point says nothing about another.
+#[test]
+fn the_entry_point_is_the_name_the_caller_gives() {
+    let wasm = assemble(
+        r#"(module (memory (export "memory") 1)
+             (func (export "other") (result i32) (i32.const 0)))"#,
+    );
+
+    assert!(xrpl_wasm_vm::check(&wasm, "other").is_ok());
+    assert!(xrpl_wasm_vm::check(&wasm, ENTRY).is_err());
+}
+
+/// Both halves of the entry point's type are screened: a module returning the
+/// wrong thing, or taking anything at all, would fail the run's typed lookup.
+#[test]
+fn an_entry_point_of_the_wrong_type_does_not_pass() {
+    for (signature, body) in [
+        ("(result i64)", "(i64.const 0)"),
+        ("(param i32) (result i32)", "(i32.const 0)"),
+        ("", "(nop)"),
+    ] {
+        let refusal = refusal(&format!(
+            r#"(module (memory (export "memory") 1)
+                 (func (export "finish") {signature} {body}))"#
+        ));
+        let refusal = assert_stage!(refusal, CheckError::EntryPoint(_)).to_string();
+        assert_eq!(
+            refusal, "entry point 'finish' has the wrong signature, expected '() -> i32'",
+            "{signature}"
+        );
+    }
+}
+
+/// An export of the entry point's name that is not a function at all is a third
+/// case, and named as such: nothing is missing and no signature is wrong.
+#[test]
+fn an_entry_point_that_is_not_a_function_does_not_pass() {
+    let refusal = refusal(
+        r#"(module (memory (export "memory") 1) (global (export "finish") i32 (i32.const 0)))"#,
+    );
+    let refusal = assert_stage!(refusal, CheckError::EntryPoint(_)).to_string();
+    assert_eq!(refusal, "export 'finish' is not a function");
+}
+
+// ---------------------------------------------------------------------------
+// Agreement with a run
+// ---------------------------------------------------------------------------
+
+/// A module with no linear memory to export passes. A contract that makes no host
+/// call needs none, and one that does is refused at the call and charged — a
+/// runtime fault, not a malformed module.
+#[test]
+fn a_module_exporting_no_memory_passes() {
+    let wat = r#"(module (func (export "finish") (result i32) (i32.const 0)))"#;
+    passes(wat);
+
+    let host = FakeHost::new();
+    assert_eq!(
+        xrpl_wasm_vm::run(&assemble(wat), PLENTY_OF_GAS, &host, ENTRY)
+            .expect("a module that calls no host function needs no memory")
+            .result,
+        0
+    );
+}
+
+/// Modules spanning what screening decides, each also put through a run.
+fn modules() -> Vec<(&'static str, String)> {
+    vec![
+        (
+            "a runnable contract",
+            module(&[import::LDGR_INDEX, ONE_PAGE], "(i32.const 0)"),
+        ),
+        (
+            "a contract that traps",
+            module(&[ONE_PAGE], "(unreachable)"),
+        ),
+        (
+            "a disabled feature",
+            module(&[ONE_PAGE], "(i32.extend8_s (i32.const 1))"),
+        ),
+        (
+            "an unknown host function",
+            module(
+                &[
+                    r#"(import "host_lib" "nope" (func $f (result i32)))"#,
+                    ONE_PAGE,
+                ],
+                "(call $f)",
+            ),
+        ),
+        (
+            "an import from another module",
+            module(
+                &[
+                    r#"(import "env" "ldgr_index" (func $f (param i32 i32) (result i32)))"#,
+                    ONE_PAGE,
+                ],
+                "(i32.const 0)",
+            ),
+        ),
+        (
+            "a host function imported as a global",
+            module(
+                &[r#"(import "host_lib" "trace" (global $g i32))"#, ONE_PAGE],
+                "(global.get $g)",
+            ),
+        ),
+        (
+            "no entry point",
+            r#"(module (memory (export "memory") 1)
+                 (func (export "other") (result i32) (i32.const 0)))"#
+                .to_string(),
+        ),
+        (
+            "an entry point of the wrong type",
+            r#"(module (memory (export "memory") 1)
+                 (func (export "finish") (result i64) (i64.const 0)))"#
+                .to_string(),
+        ),
+    ]
+}
+
+/// Screening refuses a module exactly when a run would refuse it at one of the
+/// three stages screening covers — nothing it rejects would have run, and nothing
+/// it passes stops before the entry point is called. The exceptions are the ones
+/// [`what_static_screening_cannot_see`] lists.
+#[test]
+fn screening_and_a_run_agree() {
+    let host = FakeHost::new();
+
+    for (label, wat) in modules() {
+        let wasm = assemble(&wat);
+        let refused_early = match xrpl_wasm_vm::run(&wasm, PLENTY_OF_GAS, &host, ENTRY) {
+            Err(failure) => matches!(
+                failure.error,
+                RunError::Compile(_) | RunError::Instantiate(_) | RunError::EntryPoint(_)
+            ),
+            Ok(_) => false,
+        };
+
+        assert_eq!(
+            xrpl_wasm_vm::check(&wasm, ENTRY).is_err(),
+            refused_early,
+            "{label}"
+        );
+    }
+}
+
+/// A module asking for more memory than the engine grants is refused, so the
+/// contract that could never run does not reach the ledger. The cap itself passes.
+#[test]
+fn an_exported_memory_past_the_cap_does_not_pass() {
+    let wat = module(
+        &[&format!(
+            r#"(memory (export "memory") {})"#,
+            MAX_MEMORY_PAGES + 1
+        )],
+        "(i32.const 0)",
+    );
+    let refusal = assert_stage!(refusal(&wat), CheckError::Memory(_)).to_string();
+    assert!(refusal.contains("past the 128-page cap"), "{refusal}");
+
+    passes(&module(
+        &[&format!(r#"(memory (export "memory") {MAX_MEMORY_PAGES})"#)],
+        "(i32.const 0)",
+    ));
+}
+
+/// A declared *maximum* past the cap is legal and simply unreachable, so screening
+/// must not turn it away: `vm_limits` runs this very module to completion.
+#[test]
+fn a_declared_maximum_past_the_cap_still_passes() {
+    passes(&module(
+        &[&format!(
+            r#"(memory (export "memory") 1 {})"#,
+            MAX_MEMORY_PAGES + 1
+        )],
+        "(i32.const 0)",
+    ));
+}
+
+/// A module asking for more table than the engine grants is refused for the same
+/// reason a memory is. The cap itself passes.
+#[test]
+fn an_exported_table_past_the_cap_does_not_pass() {
+    let wat = module(
+        &[&format!(
+            r#"(table (export "t") {} funcref)"#,
+            MAX_TABLE_ELEMENTS + 1
+        )],
+        "(i32.const 0)",
+    );
+    let refusal = assert_stage!(refusal(&wat), CheckError::Table(_)).to_string();
+    assert!(refusal.contains("past the 1024-element cap"), "{refusal}");
+
+    passes(&module(
+        &[&format!(
+            r#"(table (export "t") {MAX_TABLE_ELEMENTS} funcref)"#
+        )],
+        "(i32.const 0)",
+    ));
+}
+
+/// Both caps are applied in one pass over the exports, so neither may end the walk
+/// early: a passing memory must not hide a failing table declared after it, and a
+/// passing table must not hide a failing memory.
+#[test]
+fn one_pass_screens_both_resources() {
+    let after_a_passing_memory = refusal(&module(
+        &[
+            ONE_PAGE,
+            &format!(r#"(table (export "t") {} funcref)"#, MAX_TABLE_ELEMENTS + 1),
+        ],
+        "(i32.const 0)",
+    ));
+    assert_stage!(after_a_passing_memory, CheckError::Table(_));
+
+    let after_a_passing_table = refusal(&module(
+        &[
+            r#"(table (export "t") 1 funcref)"#,
+            &format!(r#"(memory (export "memory") {})"#, MAX_MEMORY_PAGES + 1),
+        ],
+        "(i32.const 0)",
+    ));
+    assert_stage!(after_a_passing_table, CheckError::Memory(_));
+}
+
+/// As with memory, a declared *maximum* past the cap is unreachable rather than
+/// wrong: `vm_limits` runs this very module to completion.
+#[test]
+fn a_declared_table_maximum_past_the_cap_still_passes() {
+    passes(&module(
+        &[&format!(
+            r#"(table (export "t") 1 {} funcref)"#,
+            MAX_TABLE_ELEMENTS + 1
+        )],
+        "(i32.const 0)",
+    ));
+}
+
+/// The gap, listed rather than described. A memory or a table a module keeps to
+/// itself is not in its exports, so these are the modules that pass screening and
+/// then fail to *instantiate* — which is why a run's refusal at that stage cannot be
+/// read as the node's fault.
+///
+/// The two entries are not equally remote. A contract needs an exported memory to
+/// make any host call, so the memory row can do nothing but compute and the SDK does
+/// not produce one. A table, though, is *normally* unexported — Rust exports
+/// `__indirect_function_table` only under `--export-table` — so the table row is the
+/// shape a hostile module actually takes, and the store's limiter is the only thing
+/// standing in front of it.
+#[test]
+fn what_static_screening_cannot_see() {
+    let host = FakeHost::new();
+
+    for (label, declaration) in [
+        ("memory", format!("(memory {})", MAX_MEMORY_PAGES + 1)),
+        (
+            "table",
+            format!("(table {} funcref)", MAX_TABLE_ELEMENTS + 1),
+        ),
+    ] {
+        let wat = format!(
+            r#"(module {declaration}
+                 (func (export "finish") (result i32) (i32.const 0)))"#
+        );
+
+        passes(&wat);
+
+        let failure = match xrpl_wasm_vm::run(&assemble(&wat), PLENTY_OF_GAS, &host, ENTRY) {
+            Err(failure) => failure,
+            Ok(outcome) => panic!(
+                "the store's limiter must refuse the {label}, but the module returned {}",
+                outcome.result
+            ),
+        };
+        assert!(
+            matches!(failure.error, RunError::Instantiate(_)),
+            "{label}: {failure}"
+        );
+    }
+}
+
+/// A start section is guest code, so screening cannot see whether it traps — and does
+/// not have to. A trap is the guest's fault wherever it happens, so the run charges the
+/// contract for what it burned instead of reporting a module the node should have
+/// screened.
+#[test]
+fn a_start_section_screening_cannot_see_is_charged_as_a_trap() {
+    let host = FakeHost::new();
+    let wat = format!(
+        r#"(module {ONE_PAGE}
+             (func $init (unreachable))
+             (start $init)
+             (func (export "finish") (result i32) (i32.const 0)))"#
+    );
+
+    passes(&wat);
+
+    let failure = xrpl_wasm_vm::run(&assemble(&wat), PLENTY_OF_GAS, &host, ENTRY)
+        .expect_err("a start section that traps must not complete the run");
+    assert!(matches!(failure.error, RunError::Trap(_)), "{failure}");
+    assert!(
+        failure.fuel_used > 0,
+        "charged for what it burned: {failure}"
+    );
+}

crates/xrpl-wasm-vm/tests/vm_limits.rs

@@ -0,0 +1,642 @@
+//! What the engine refuses outright: modules it will not compile, will not
+//! instantiate, or cannot find an entry point in — plus the memory and table caps.
+//!
+//! These are the sandbox's outer wall. Everything here fails the run rather than
+//! returning a code to the guest, so each test reads the failure's message.
+
+mod support;
+
+use support::{
+    FakeHost, ONE_PAGE, PLENTY_OF_GAS, failure, import, module, run, run_entry, run_with_gas,
+};
+use xrpl_wasm_vm::{MAX_MEMORY_PAGES, MAX_TABLE_ELEMENTS, RunError};
+
+/// Assert which stage a run failed at, because the caller maps the stages to
+/// different outcomes. A stage is one `RunError` variant, so the expectation is a
+/// pattern; the failure comes back out for the tests that also read its message.
+macro_rules! assert_stage {
+    ($failure:expr, $stage:pat) => {{
+        let failure = $failure;
+        assert!(
+            matches!(failure.error, $stage),
+            concat!("expected a ", stringify!($stage), " failure, got: {}"),
+            failure
+        );
+        failure
+    }};
+}
+
+// ---------------------------------------------------------------------------
+// Linear memory
+// ---------------------------------------------------------------------------
+
+/// A module declaring more than the cap fails to instantiate — the limit applies
+/// to the initial memory, not only to growth.
+#[test]
+fn an_initial_memory_past_the_cap_is_refused() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!(
+            r#"(memory (export "memory") {})"#,
+            MAX_MEMORY_PAGES + 1
+        )],
+        "(i32.const 0)",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+}
+
+/// The cap itself is allowed.
+#[test]
+fn an_initial_memory_at_the_cap_is_allowed() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!(r#"(memory (export "memory") {MAX_MEMORY_PAGES})"#)],
+        "(i32.const 0)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+}
+
+/// Growth up to the cap succeeds; growth past it traps rather than answering -1 as
+/// `memory.grow` otherwise would, because the engine's limiter sets
+/// `trap_on_grow_failure(true)`.
+#[test]
+fn growth_stops_at_the_cap() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[ONE_PAGE],
+        &format!("(memory.grow (i32.const {}))", MAX_MEMORY_PAGES - 1),
+    );
+    assert_eq!(
+        run(&wat, &host).expect("should run").result,
+        1,
+        "growing to exactly the cap answers the previous size"
+    );
+
+    let wat = module(
+        &[ONE_PAGE],
+        &format!("(memory.grow (i32.const {MAX_MEMORY_PAGES}))"),
+    );
+    assert_stage!(failure(&wat, &host), RunError::Trap(_));
+}
+
+/// A module may declare a maximum above the cap: the cap is enforced on the initial
+/// memory and on growth, not on the memory type's declared bound.
+#[test]
+fn a_declared_maximum_past_the_cap_is_allowed_but_unreachable() {
+    let host = FakeHost::new();
+    let memory = format!(r#"(memory (export "memory") 1 {})"#, MAX_MEMORY_PAGES + 1);
+
+    let wat = module(&[&memory], "(i32.const 0)");
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+
+    let wat = module(
+        &[&memory],
+        &format!("(memory.grow (i32.const {MAX_MEMORY_PAGES}))"),
+    );
+    assert_stage!(failure(&wat, &host), RunError::Trap(_));
+}
+
+// ---------------------------------------------------------------------------
+// Tables
+// ---------------------------------------------------------------------------
+
+/// A table's whole cost is paid at instantiation: wasmi writes all 8 bytes of every
+/// element before the guest's first instruction, so a module declaring more than the
+/// cap must be refused there rather than charged for it.
+#[test]
+fn an_initial_table_past_the_cap_is_refused() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!("(table {} funcref)", MAX_TABLE_ELEMENTS + 1)],
+        "(i32.const 0)",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+}
+
+/// The cap itself is allowed.
+#[test]
+fn an_initial_table_at_the_cap_is_allowed() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!("(table {MAX_TABLE_ELEMENTS} funcref)")],
+        "(i32.const 0)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+}
+
+/// The cap binds a table the module keeps to itself, which is the case that matters:
+/// a contract has no reason to export its table, so screening never sees the one a
+/// hostile module declares.
+#[test]
+fn the_table_cap_binds_an_unexported_table() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!("(table {} funcref)", u32::from(u16::MAX) * 100)],
+        "(i32.const 0)",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+}
+
+/// A declared *maximum* past the cap is legal and simply unreachable, mirroring what
+/// linear memory allows. Nothing can reach it: `table.grow` is a reference-types
+/// instruction and the engine turns that feature off, so a table's declared minimum
+/// is also its final size.
+#[test]
+fn a_declared_table_maximum_past_the_cap_is_allowed_but_unreachable() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[&format!(
+            "(table 1 {} funcref)",
+            u64::try_from(MAX_TABLE_ELEMENTS).expect("fits") + 1
+        )],
+        "(i32.const 0)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+}
+
+// ---------------------------------------------------------------------------
+// Engine configuration
+// ---------------------------------------------------------------------------
+
+/// One row per feature `build_wasm_engine` turns off: the smallest module that uses
+/// it, and the fragment of wasmi's refusal that names the feature. A row declaring
+/// its own memory omits [`ONE_PAGE`], or it is refused for having two memories
+/// instead.
+fn disabled_features() -> Vec<(&'static str, Vec<&'static str>, &'static str, &'static str)> {
+    vec![
+        (
+            "wasm_multi_value",
+            vec![
+                ONE_PAGE,
+                "(func $two (result i32 i32) (i32.const 1) (i32.const 2))",
+            ],
+            "(call $two) (drop) (drop) (i32.const 0)",
+            "multi-value",
+        ),
+        (
+            "wasm_sign_extension",
+            vec![ONE_PAGE],
+            "(i32.extend8_s (i32.const 1))",
+            "sign extension",
+        ),
+        (
+            "wasm_bulk_memory",
+            vec![ONE_PAGE],
+            "(memory.fill (i32.const 0) (i32.const 0) (i32.const 1)) (i32.const 0)",
+            "bulk memory",
+        ),
+        (
+            "wasm_reference_types",
+            vec![ONE_PAGE, "(table 1 externref)"],
+            "(i32.const 0)",
+            "reference types",
+        ),
+        // The proposal covers mutable globals crossing the module boundary; an
+        // internal one is core wasm and stays allowed — see the test below.
+        (
+            "wasm_mutable_global",
+            vec![ONE_PAGE, r#"(global (export "g") (mut i32) (i32.const 0))"#],
+            "(i32.const 0)",
+            "mutable global",
+        ),
+        (
+            "wasm_tail_call",
+            vec![ONE_PAGE, "(func $f (result i32) (i32.const 0))"],
+            "(return_call $f)",
+            "tail call",
+        ),
+        // Arithmetic in a constant initialiser. wasmi names the operator rather
+        // than the proposal here.
+        (
+            "wasm_extended_const",
+            vec![
+                ONE_PAGE,
+                "(global $g i32 (i32.add (i32.const 1) (i32.const 2)))",
+            ],
+            "(global.get $g)",
+            "non-constant operator",
+        ),
+        (
+            "wasm_multi_memory",
+            vec![ONE_PAGE, "(memory 1)"],
+            "(i32.const 0)",
+            "multiple memories",
+        ),
+        (
+            "wasm_memory64",
+            vec![r#"(memory (export "memory") i64 1)"#],
+            "(i32.const 0)",
+            "memory64",
+        ),
+        (
+            "wasm_custom_page_sizes",
+            vec![r#"(memory (export "memory") 1 (pagesize 1))"#],
+            "(i32.const 0)",
+            "custom page sizes",
+        ),
+        (
+            "wasm_wide_arithmetic",
+            vec![ONE_PAGE],
+            "(drop (i64.add128 (i64.const 1) (i64.const 2) (i64.const 3) (i64.const 4)))
+             (i32.const 0)",
+            "wide arithmetic",
+        ),
+        // Determinism across nodes is the reason floats are off.
+        (
+            "floats",
+            vec![ONE_PAGE],
+            "(drop (f64.add (f64.const 1) (f64.const 2))) (i32.const 0)",
+            "floating-point",
+        ),
+    ]
+}
+
+/// Every feature the engine disables is refused, and refused for that reason.
+///
+/// `wasm_custom_page_sizes` and `wasm_wide_arithmetic` are off by default in wasmi
+/// 1.1 (`engine/config.rs:72,74`), so their rows guard against wasmi changing that
+/// default rather than against this engine's own config.
+#[test]
+fn every_disabled_feature_is_refused_by_name() {
+    let host = FakeHost::new();
+
+    for (knob, parts, body, expected) in disabled_features() {
+        let wat = module(&parts, body);
+        let failure = assert_stage!(failure(&wat, &host), RunError::Compile(_)).to_string();
+
+        assert!(
+            failure.contains(expected),
+            "{knob}: expected a refusal mentioning {expected:?}, got: {failure}"
+        );
+    }
+}
+
+/// The three knobs [`every_disabled_feature_is_refused_by_name`] cannot cover. The
+/// engine is a process-wide `LazyLock`, so a test observes the one configuration
+/// `build_wasm_engine` makes: a knob masked by another, or with no caller-visible
+/// effect, has no distinguishing module.
+#[test]
+fn the_knobs_without_a_module_of_their_own() {
+    let host = FakeHost::new();
+
+    // `wasm_saturating_float_to_int(false)`: every saturating conversion takes a
+    // float operand, so `floats(false)` refuses it first, as the message shows.
+    let wat = module(&[ONE_PAGE], "(i32.trunc_sat_f32_s (f32.const 1))");
+    let refusal = failure(&wat, &host).to_string();
+    assert!(refusal.contains("floating-point"), "{refusal}");
+    assert!(!refusal.contains("saturating"), "{refusal}");
+
+    // `ignore_custom_sections(true)`: governs whether wasmi retains custom
+    // sections, not accept/reject, so this pins only that one is harmless.
+    let wat = module(
+        &[ONE_PAGE, r#"(@custom "note" "ignored")"#],
+        "(i32.const 0)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+
+    // `consume_fuel(true)`: with it off, `Store::set_fuel` fails and `run` returns
+    // before instantiating, so every test in the suite fails.
+    let wat = module(&[ONE_PAGE], "(i32.const 0)");
+    assert!(run(&wat, &host).expect("should run").fuel_used > 0);
+}
+
+/// A mutable global the module keeps to itself is core wasm, so the disabled
+/// proposal does not reach it: a guest can still have mutable state.
+#[test]
+fn an_internal_mutable_global_is_still_allowed() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[ONE_PAGE, "(global $g (mut i32) (i32.const 0))"],
+        "(global.set $g (i32.const 7)) (global.get $g)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 7);
+}
+
+/// Bytes that are not a wasm module at all.
+#[test]
+fn garbage_does_not_compile() {
+    let host = FakeHost::new();
+
+    for bytes in [b"".as_slice(), b"not wasm", &[0x00, 0x61, 0x73, 0x6d]] {
+        let failure = xrpl_wasm_vm::run(bytes, PLENTY_OF_GAS, &host, support::ENTRY)
+            .expect_err("garbage must not compile");
+        assert_stage!(failure, RunError::Compile(_));
+    }
+}
+
+/// The VM takes wasm binaries, and text is not one. wasmi's `wat` feature is on by
+/// default and would have `Module::new` assemble text too, so the crate builds
+/// wasmi without it; turning it back on would make this transaction blob valid.
+#[test]
+fn the_vm_refuses_a_text_format_module() {
+    let host = FakeHost::new();
+    let text = module(&[ONE_PAGE], "(i32.const 0)");
+
+    let failure = xrpl_wasm_vm::run(text.as_bytes(), PLENTY_OF_GAS, &host, support::ENTRY)
+        .expect_err("text must not compile as a module");
+    assert_stage!(failure, RunError::Compile(_));
+
+    // The same module, assembled first, runs: the text is sound and only the
+    // format was refused.
+    assert_eq!(run(&text, &host).expect("should run").result, 0);
+}
+
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+
+/// A module may import fewer host functions than are registered, but not more:
+/// an import the linker does not define fails instantiation.
+#[test]
+fn an_unknown_import_fails_instantiation() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[
+            r#"(import "host_lib" "no_such_function" (func $f (param i32) (result i32)))"#,
+            ONE_PAGE,
+        ],
+        "(call $f (i32.const 0))",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+}
+
+/// Host functions are registered under one module name — `host_lib`, the name the
+/// guest SDK and this repo's fixtures import from — and a guest naming a different
+/// one does not link. `env` is in the list because that is what plain clang emits.
+#[test]
+fn the_import_module_name_must_match() {
+    let host = FakeHost::new();
+
+    for module_name in ["host", "env", ""] {
+        let wat = module(
+            &[
+                &format!(
+                    r#"(import "{module_name}" "ldgr_index" (func $f (param i32 i32) (result i32)))"#
+                ),
+                ONE_PAGE,
+            ],
+            "(call $f (i32.const 0) (i32.const 4))",
+        );
+        assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+    }
+}
+
+/// An import spelled with the wrong signature does not link even under the right
+/// name, which is what makes the registered signatures load-bearing.
+#[test]
+fn an_import_with_the_wrong_signature_fails_instantiation() {
+    let host = FakeHost::new();
+
+    for signature in [
+        "(param i32) (result i32)",         // too few parameters
+        "(param i32 i32 i32) (result i32)", // too many
+        "(param i64 i64) (result i32)",     // wrong parameter types
+        "(param i32 i32) (result i64)",     // wrong result type
+        "(param i32 i32)",                  // no result
+    ] {
+        let wat = module(
+            &[
+                &format!(r#"(import "host_lib" "ldgr_index" (func $f {signature}))"#),
+                ONE_PAGE,
+            ],
+            "(i32.const 0)",
+        );
+        assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+    }
+}
+
+/// A module that imports a host function it never calls still has to link.
+#[test]
+fn an_unused_import_is_still_linked() {
+    let host = FakeHost::new();
+
+    let wat = module(
+        &[import::LDGR_INDEX, import::TRACE, ONE_PAGE],
+        "(i32.const 0)",
+    );
+    assert_eq!(run(&wat, &host).expect("should run").result, 0);
+}
+
+// ---------------------------------------------------------------------------
+// The start section
+// ---------------------------------------------------------------------------
+
+/// A start section runs guest code during instantiation, before the entry point
+/// is even looked up, and `set_fuel` and the memory limiter are both installed by
+/// then — so it is metered like any other guest code, and a run it stops is
+/// charged for what it burned.
+///
+/// Reported as a **trap**, not as a module that would not instantiate: a trap is the
+/// guest's fault wherever it happens, and the stage a run stopped at is not what the
+/// caller maps. Filing it under the stage would put a contract's own defect among the
+/// faults a caller treats as the node's, and charge nothing for the instructions the
+/// contract burned reaching it.
+#[test]
+fn a_trapping_start_section_is_a_guest_trap_and_is_charged() {
+    let host = FakeHost::new();
+
+    let wat = format!(
+        r#"(module {ONE_PAGE}
+             (func $init (unreachable))
+             (start $init)
+             (func (export "finish") (result i32) (i32.const 0)))"#
+    );
+    let failure = assert_stage!(
+        run_with_gas(&wat, PLENTY_OF_GAS, &host)
+            .expect_err("a start section that traps must not complete the run"),
+        RunError::Trap(_)
+    );
+    assert!(
+        failure.fuel_used > 0,
+        "the start section's instructions are metered: {failure}"
+    );
+}
+
+/// What `RunError::Instantiate` is left to mean: a module the linker or the store
+/// would not accept, rather than one whose guest code failed. Its two shapes, so the
+/// variant is not left standing for nothing.
+#[test]
+fn instantiation_failure_is_a_module_the_engine_will_not_accept() {
+    let host = FakeHost::new();
+
+    // The linker defines no such import.
+    let wat = module(
+        &[
+            r#"(import "host_lib" "no_such_function" (func $f (result i32)))"#,
+            ONE_PAGE,
+        ],
+        "(call $f)",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+
+    // The store's limiter will not grant the memory, and does not trap to say so.
+    let wat = module(
+        &[&format!("(memory {})", MAX_MEMORY_PAGES + 1)],
+        "(i32.const 0)",
+    );
+    assert_stage!(failure(&wat, &host), RunError::Instantiate(_));
+}
+
+/// A start section that runs out of gas is reported as out of gas, not as a module
+/// that would not instantiate. The stage a run stopped at is not what the caller
+/// maps — the reason is — and gas exhaustion is one outcome wherever the guest
+/// reaches it.
+#[test]
+fn a_start_section_that_exhausts_gas_is_out_of_gas_not_an_instantiation_failure() {
+    const GAS: u64 = 10_000;
+
+    let host = FakeHost::new();
+    let wat = format!(
+        r#"(module {ONE_PAGE}
+             (func $init (loop $l (br $l)))
+             (start $init)
+             (func (export "finish") (result i32) (i32.const 0)))"#
+    );
+
+    let failure = assert_stage!(
+        run_with_gas(&wat, GAS, &host).expect_err("an endless start section must not instantiate"),
+        RunError::OutOfGas
+    );
+    assert_eq!(
+        failure.fuel_used, GAS,
+        "a runaway start section burns the whole limit"
+    );
+}
+
+/// A start section cannot make a host call that needs guest memory, even in a
+/// module that exports one: the memory is resolved from the *instance's* exports,
+/// and instantiation is what produces the instance, so a call made while it is
+/// still running has no memory to work in and ends the run.
+///
+/// Not a choice: `Module::instantiate` is `pub(crate)` in wasmi, so instantiation
+/// cannot be split from the start section to resolve the memory in between.
+#[test]
+fn a_start_section_cannot_make_a_host_call() {
+    let host = FakeHost::new();
+
+    let wat = format!(
+        r#"(module {ldgr_index} {ONE_PAGE}
+             (func $init (drop (call $ldgr_index (i32.const 0) (i32.const 4))))
+             (start $init)
+             (func (export "finish") (result i32) (i32.const 0)))"#,
+        ldgr_index = import::LDGR_INDEX
+    );
+
+    let failure = assert_stage!(
+        run_with_gas(&wat, PLENTY_OF_GAS, &host)
+            .expect_err("a host call from a start section must not be served"),
+        RunError::NoMemory
+    );
+    assert!(
+        failure.fuel_used > 0,
+        "the start section is metered up to the refused call: {failure}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// The entry point
+// ---------------------------------------------------------------------------
+
+#[test]
+fn a_missing_entry_point_fails() {
+    let host = FakeHost::new();
+
+    let wat = r#"(module (memory (export "memory") 1) (func (export "other") (result i32) (i32.const 0)))"#;
+    let failure = assert_stage!(
+        run_with_gas(wat, PLENTY_OF_GAS, &host)
+            .expect_err("a module without the entry point must not run"),
+        RunError::EntryPoint(_)
+    );
+    assert!(
+        failure.to_string().contains("no entry point 'finish'"),
+        "{failure}"
+    );
+}
+
+/// The entry point is looked up by the name the caller asks for.
+#[test]
+fn the_entry_point_is_the_name_the_caller_gives() {
+    let host = FakeHost::new();
+
+    let wat = r#"(module (memory (export "memory") 1) (func (export "other") (result i32) (i32.const 9)))"#;
+    let outcome = run_entry(wat, &host, "other").expect("should run");
+    assert_eq!(outcome.result, 9);
+}
+
+/// The entry point must take nothing and return an `i32`. A module that exports the
+/// name with another signature is told so, rather than being told the export is
+/// missing: wasmi answers both cases with one error, and "no entry point" would send
+/// a contract author looking for a function they already have.
+#[test]
+fn an_entry_point_of_the_wrong_type_fails() {
+    let host = FakeHost::new();
+
+    for signature in ["(result i64)", "(param i32) (result i32)", ""] {
+        let body = if signature.contains("result i64") {
+            "(i64.const 0)"
+        } else if signature.is_empty() {
+            "(nop)"
+        } else {
+            "(i32.const 0)"
+        };
+        let wat = format!(
+            r#"(module (memory (export "memory") 1) (func (export "finish") {signature} {body}))"#
+        );
+        let failure = assert_stage!(
+            run_with_gas(&wat, PLENTY_OF_GAS, &host)
+                .expect_err("a wrongly-typed entry point must not run"),
+            RunError::EntryPoint(_)
+        )
+        .to_string();
+        assert!(
+            failure.contains("entry point 'finish' has the wrong signature"),
+            "{signature}: {failure}"
+        );
+        assert!(
+            !failure.contains("no entry point"),
+            "a present export must not be reported as absent — {signature}: {failure}"
+        );
+    }
+}
+
+/// An export of the entry point's name that is not a function at all is a third
+/// case, and named as such: nothing is missing and no signature is wrong.
+#[test]
+fn an_entry_point_that_is_not_a_function_fails() {
+    let host = FakeHost::new();
+
+    let wat =
+        r#"(module (memory (export "memory") 1) (global (export "finish") i32 (i32.const 0)))"#;
+    let failure = assert_stage!(
+        run_with_gas(wat, PLENTY_OF_GAS, &host).expect_err("a non-function export must not run"),
+        RunError::EntryPoint(_)
+    )
+    .to_string();
+    assert!(
+        failure.contains("export 'finish' is not a function"),
+        "{failure}"
+    );
+}
+
+/// A guest that traps fails the run rather than returning a value.
+#[test]
+fn a_trapping_guest_fails_the_run() {
+    let host = FakeHost::new();
+
+    let wat = module(&[ONE_PAGE], "(unreachable)");
+    assert_stage!(failure(&wat, &host), RunError::Trap(_));
+
+    // An out-of-bounds guest access is a trap too, caught by the engine rather
+    // than anything the host is asked about.
+    let wat = module(&[ONE_PAGE], "(i32.load (i32.const 100000))");
+    assert_stage!(failure(&wat, &host), RunError::Trap(_));
+}

docs/build/environment.md

@@ -1,5 +1,5 @@
 Our [build instructions][BUILD.md] assume you have a C++ development
-environment complete with Git, Python, Conan, CMake, and a C++ compiler.
+environment complete with Git, Python, Conan, CMake, Rust, and a C++ compiler.
 This document explains how to set one up.
 
 [BUILD.md]: ../../BUILD.md
@@ -36,19 +36,17 @@ compiler building. Treat support for anything outside the table as best-effort.
 
 Besides a compiler, building `xrpld` requires:
 
-| Tool                                        | Minimum version |
-| ------------------------------------------- | --------------- |
-| [Git](https://git-scm.com/downloads)        | any recent      |
-| [Python](https://www.python.org/downloads/) | 3.11            |
-| [Conan](https://conan.io/downloads.html)    | 2.17            |
-| [CMake](https://cmake.org/download/)        | 3.16            |
+| Tool                                        | Minimum version          |
+| ------------------------------------------- | ------------------------ |
+| [Git](https://git-scm.com/downloads)        | any recent               |
+| [Python](https://www.python.org/downloads/) | 3.11                     |
+| [Conan](https://conan.io/downloads.html)    | 2.17                     |
+| [CMake](https://cmake.org/download/)        | 3.16                     |
+| [Rust](https://rustup.rs)                   | 1.95 (see [Rust](#rust)) |
 
 On Linux and macOS, the [Nix development shell](./nix.md) provides all of them
 (see below). On Windows they have to be installed manually.
 
-Building with `-Drust=ON` additionally requires a Rust toolchain, see
-[Rust](#rust). A default build does not, so it is not in the table above.
-
 Once they are in place, verify that everything is installed and runnable with:
 
 ```bash
@@ -122,18 +120,14 @@ manually:
   "x64 Native Tools Command Prompt". CI configures CMake with the
   `Visual Studio 18 2026` generator.
 - [Git for Windows](https://git-scm.com/download/win)
-- Python, Conan, and CMake, at the versions listed in
+- Python, Conan, CMake, and Rust, at the versions listed in
   [Required tools](#required-tools).
-- a [Rust toolchain](https://rustup.rs) — only needed to build with
-  `-Drust=ON`, see [Rust](#rust)
 
 ## Rust
 
 The repository contains a Rust workspace in [`crates/`](../../crates), whose
-crates are exposed to C++ through [cxx](https://cxx.rs) bindings. It is **not**
-part of a default build: the CMake `rust` option is OFF by default, and with it
-off no Rust toolchain is needed. It is only required when configuring with
-`-Drust=ON` (which is what CI does), see [Options](../../BUILD.md#options).
+crates are exposed to C++ through [cxx](https://cxx.rs) bindings and compiled by
+the CMake build, so a Rust toolchain is required.
 
 The toolchain (`cargo`, `rustc`) is pinned to the channel in
 [`rust-toolchain.toml`](../../rust-toolchain.toml) at the repository root. If

docs/build/nix.md

@@ -128,9 +128,8 @@ Coverage builds (`-Dcoverage=ON`) work in the `gcc` shell (and `gcc-plain` on Li
 each ships a `gcov` matching its compiler, since Nix's cc-wrapper does not expose one.
 The `clang` shells do not include `llvm-cov`, so use a `gcc` shell for coverage.
 
-Builds of the Rust crates (`-Drust=ON`) also work out of the box: every shell
-provides the Rust toolchain pinned in
-[`rust-toolchain.toml`](../../rust-toolchain.toml) (see
+The Rust toolchain the build needs is included too: every shell provides the
+channel pinned in [`rust-toolchain.toml`](../../rust-toolchain.toml) (see
 [Rust](./environment.md#rust)), plus the `cargo-audit`, `cargo-llvm-cov` and
 `cargo-nextest` plugins.
 

docs/install.md

@@ -92,11 +92,11 @@ wherever it appears in the repository configuration.
 2.  Add the repository, using the channel you picked in [Release channels](#release-channels):
 
     ```bash
-    cat << 'REPOFILE' | sudo tee /etc/yum.repos.d/xrplf.repo
+    cat << REPOFILE | sudo tee /etc/yum.repos.d/xrplf.repo
     [xrplf-stable]
     name=XRP Ledger Packages
     enabled=1
-    baseurl=https://packages.xrplf.org/repository/rpm-stable/$basearch/
+    baseurl=https://packages.xrplf.org/repository/rpm-stable/
     gpgcheck=1
     repo_gpgcheck=1
     gpgkey=https://packages.xrplf.org/xrplf.asc

include/xrpl/basics/Number.h

@@ -543,8 +543,21 @@ public:
     setround(RoundingMode inMode);
 
     /**
-     * Returns which mantissa scale is currently in use for normalization.
+     * Convert an integer to a RoundingMode, validating that it is in range.
      *
+     * Returns std::nullopt if the value does not correspond to a valid
+     * RoundingMode.
+     */
+    static std::optional<RoundingMode>
+    checkedRoundingMode(int mode) noexcept
+    {
+        if (mode < static_cast<int>(RoundingMode::ToNearest) ||
+            mode > static_cast<int>(RoundingMode::Upward))
+            return std::nullopt;
+        return static_cast<RoundingMode>(mode);
+    }
+
+    /**
      * If you think you need to call this outside of unit tests, no you don't.
      */
     static MantissaRange::MantissaScale

include/xrpl/ledger/View.h

@@ -24,7 +24,6 @@
 #include <optional>
 #include <set>
 #include <utility>
-#include <vector>
 
 namespace xrpl {
 
@@ -199,10 +198,7 @@ dirLink(
  *      if withdrawing to self.
  *    - If withdrawing to self, succeed.
  *    - If not, checks if the receiver requires deposit authorization, and if
- *      the sender has it (account-based or credential-based).
- *    - Expects any credentials passed in to already exist in the ledger, and
- *      returns an internal error otherwise. Validate them beforehand with
- *      credentials::valid().
+ *      the sender has it.
  *    - Checks that the receiver will not exceed the limit (IOU trustline limit
  *      or MPT MaximumAmount).
  */
@@ -213,8 +209,7 @@ canWithdraw(
     AccountID const& to,
     SLE::const_ref toSle,
     STAmount const& amount,
-    bool hasDestinationTag,
-    std::optional<std::vector<uint256>> const& credentialIDs = std::nullopt);
+    bool hasDestinationTag);
 
 /**
  * Checks that can withdraw funds from an object to itself or a destination.
@@ -227,10 +222,7 @@ canWithdraw(
  *      if withdrawing to self.
  *    - If withdrawing to self, succeed.
  *    - If not, checks if the receiver requires deposit authorization, and if
- *      the sender has it (account-based or credential-based).
- *    - Expects any credentials passed in to already exist in the ledger, and
- *      returns an internal error otherwise. Validate them beforehand with
- *      credentials::valid().
+ *      the sender has it.
  *    - Checks that the receiver will not exceed the limit (IOU trustline limit
  *      or MPT MaximumAmount).
  */
@@ -240,25 +232,20 @@ canWithdraw(
     AccountID const& from,
     AccountID const& to,
     STAmount const& amount,
-    bool hasDestinationTag,
-    std::optional<std::vector<uint256>> const& credentialIDs = std::nullopt);
+    bool hasDestinationTag);
 
 /**
  * Checks that can withdraw funds from an object to itself or a destination.
  *
  * The receiver may be either the submitting account (sfAccount) or a different
- * destination account (sfDestination). Credentials, if any, are taken from the
- * transaction's sfCredentialIDs field.
+ * destination account (sfDestination).
  *
  *    - Checks that the receiver account exists.
  *    - If the receiver requires a destination tag, check that one exists, even
  *      if withdrawing to self.
  *    - If withdrawing to self, succeed.
  *    - If not, checks if the receiver requires deposit authorization, and if
- *      the sender has it (account-based or credential-based).
- *    - Expects any credentials in sfCredentialIDs to already exist in the
- *      ledger, and returns an internal error otherwise. Validate them
- *      beforehand with credentials::valid().
+ *      the sender has it.
  *    - Checks that the receiver will not exceed the limit (IOU trustline limit
  *      or MPT MaximumAmount).
  */

include/xrpl/ledger/helpers/AMMEntry.h

@@ -1,45 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Asset.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class AMMEntry : public SLEBase<ViewT, ltAMM>
-{
-public:
-    using Base = SLEBase<ViewT, ltAMM>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit AMMEntry(
-        Asset const& issue1,
-        Asset const& issue2,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::amm(issue1, issue2), view, j)
-    {
-    }
-
-    explicit AMMEntry(
-        uint256 const& ammID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::amm(ammID), view, j)
-    {
-    }
-};
-
-using RAMMEntry = AMMEntry<ReadView>;
-using WAMMEntry = AMMEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/AccountRootEntry.h

@@ -1,35 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class AccountRootEntry : public SLEBase<ViewT, ltACCOUNT_ROOT>
-{
-public:
-    using Base = SLEBase<ViewT, ltACCOUNT_ROOT>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit AccountRootEntry(
-        AccountID const& id,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::account(id), view, j)
-    {
-    }
-};
-
-using RAccountRootEntry = AccountRootEntry<ReadView>;
-using WAccountRootEntry = AccountRootEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/AmendmentsEntry.h

@@ -1,33 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class AmendmentsEntry : public SLEBase<ViewT, ltAMENDMENTS>
-{
-public:
-    using Base = SLEBase<ViewT, ltAMENDMENTS>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit AmendmentsEntry(
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::amendments(), view, j)
-    {
-    }
-};
-
-using RAmendmentsEntry = AmendmentsEntry<ReadView>;
-using WAmendmentsEntry = AmendmentsEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/BridgeEntry.h

@@ -1,36 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/STXChainBridge.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class BridgeEntry : public SLEBase<ViewT, ltBRIDGE>
-{
-public:
-    using Base = SLEBase<ViewT, ltBRIDGE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit BridgeEntry(
-        STXChainBridge const& bridge,
-        STXChainBridge::ChainType chainType,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::bridge(bridge, chainType), view, j)
-    {
-    }
-};
-
-using RBridgeEntry = BridgeEntry<ReadView>;
-using WBridgeEntry = BridgeEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/CheckEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class CheckEntry : public SLEBase<ViewT, ltCHECK>
-{
-public:
-    using Base = SLEBase<ViewT, ltCHECK>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit CheckEntry(
-        AccountID const& id,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::check(id, seq), view, j)
-    {
-    }
-
-    explicit CheckEntry(
-        uint256 const& checkID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::check(checkID), view, j)
-    {
-    }
-};
-
-using RCheckEntry = CheckEntry<ReadView>;
-using WCheckEntry = CheckEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/CredentialEntry.h

@@ -1,47 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/Slice.h>
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class CredentialEntry : public SLEBase<ViewT, ltCREDENTIAL>
-{
-public:
-    using Base = SLEBase<ViewT, ltCREDENTIAL>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit CredentialEntry(
-        AccountID const& subject,
-        AccountID const& issuer,
-        Slice const& credType,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::credential(subject, issuer, credType), view, j)
-    {
-    }
-
-    explicit CredentialEntry(
-        uint256 const& credentialID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::credential(credentialID), view, j)
-    {
-    }
-};
-
-using RCredentialEntry = CredentialEntry<ReadView>;
-using WCredentialEntry = CredentialEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/DIDEntry.h

@@ -1,35 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class DIDEntry : public SLEBase<ViewT, ltDID>
-{
-public:
-    using Base = SLEBase<ViewT, ltDID>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit DIDEntry(
-        AccountID const& account,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::did(account), view, j)
-    {
-    }
-};
-
-using RDIDEntry = DIDEntry<ReadView>;
-using WDIDEntry = DIDEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/DelegateEntry.h

@@ -1,36 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class DelegateEntry : public SLEBase<ViewT, ltDELEGATE>
-{
-public:
-    using Base = SLEBase<ViewT, ltDELEGATE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit DelegateEntry(
-        AccountID const& account,
-        AccountID const& authorizedAccount,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::delegate(account, authorizedAccount), view, j)
-    {
-    }
-};
-
-using RDelegateEntry = DelegateEntry<ReadView>;
-using WDelegateEntry = DelegateEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/DepositPreauthEntry.h

@@ -1,58 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/Slice.h>
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-#include <set>
-#include <utility>
-
-namespace xrpl {
-
-template <typename ViewT>
-class DepositPreauthEntry : public SLEBase<ViewT, ltDEPOSIT_PREAUTH>
-{
-public:
-    using Base = SLEBase<ViewT, ltDEPOSIT_PREAUTH>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit DepositPreauthEntry(
-        AccountID const& owner,
-        AccountID const& preauthorized,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::depositPreauth(owner, preauthorized), view, j)
-    {
-    }
-
-    explicit DepositPreauthEntry(
-        AccountID const& owner,
-        std::set<std::pair<AccountID, Slice>> const& authCreds,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::depositPreauth(owner, authCreds), view, j)
-    {
-    }
-
-    explicit DepositPreauthEntry(
-        uint256 const& preauthID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::depositPreauth(preauthID), view, j)
-    {
-    }
-};
-
-using RDepositPreauthEntry = DepositPreauthEntry<ReadView>;
-using WDepositPreauthEntry = DepositPreauthEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/DirectoryNodeEntry.h

@@ -1,50 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-#include <cstdint>
-
-namespace xrpl {
-
-template <typename ViewT>
-class DirectoryNodeEntry : public SLEBase<ViewT, ltDIR_NODE>
-{
-public:
-    using Base = SLEBase<ViewT, ltDIR_NODE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit DirectoryNodeEntry(
-        AccountID const& id,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::ownerDir(id), view, j)
-    {
-    }
-
-    /**
-     * Resolve a specific page of the directory rooted at @p root.
-     */
-    explicit DirectoryNodeEntry(
-        uint256 const& root,
-        std::uint64_t index,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::page(root, index), view, j)
-    {
-    }
-};
-
-using RDirectoryNodeEntry = DirectoryNodeEntry<ReadView>;
-using WDirectoryNodeEntry = DirectoryNodeEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/EscrowEntry.h

@@ -1,37 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class EscrowEntry : public SLEBase<ViewT, ltESCROW>
-{
-public:
-    using Base = SLEBase<ViewT, ltESCROW>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit EscrowEntry(
-        AccountID const& src,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::escrow(src, seq), view, j)
-    {
-    }
-};
-
-using REscrowEntry = EscrowEntry<ReadView>;
-using WEscrowEntry = EscrowEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/FeeSettingsEntry.h

@@ -1,33 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class FeeSettingsEntry : public SLEBase<ViewT, ltFEE_SETTINGS>
-{
-public:
-    using Base = SLEBase<ViewT, ltFEE_SETTINGS>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit FeeSettingsEntry(
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::feeSettings(), view, j)
-    {
-    }
-};
-
-using RFeeSettingsEntry = FeeSettingsEntry<ReadView>;
-using WFeeSettingsEntry = FeeSettingsEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/LedgerHashesEntry.h

@@ -1,33 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class LedgerHashesEntry : public SLEBase<ViewT, ltLEDGER_HASHES>
-{
-public:
-    using Base = SLEBase<ViewT, ltLEDGER_HASHES>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit LedgerHashesEntry(
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::skip(), view, j)
-    {
-    }
-};
-
-using RLedgerHashesEntry = LedgerHashesEntry<ReadView>;
-using WLedgerHashesEntry = LedgerHashesEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/LoanBrokerEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class LoanBrokerEntry : public SLEBase<ViewT, ltLOAN_BROKER>
-{
-public:
-    using Base = SLEBase<ViewT, ltLOAN_BROKER>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit LoanBrokerEntry(
-        AccountID const& owner,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::loanBroker(owner, seq), view, j)
-    {
-    }
-
-    explicit LoanBrokerEntry(
-        uint256 const& loanBrokerID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::loanBroker(loanBrokerID), view, j)
-    {
-    }
-};
-
-using RLoanBrokerEntry = LoanBrokerEntry<ReadView>;
-using WLoanBrokerEntry = LoanBrokerEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/LoanEntry.h

@@ -1,45 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class LoanEntry : public SLEBase<ViewT, ltLOAN>
-{
-public:
-    using Base = SLEBase<ViewT, ltLOAN>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit LoanEntry(
-        uint256 const& loanBrokerID,
-        SeqProxy const& loanSeq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::loan(loanBrokerID, loanSeq), view, j)
-    {
-    }
-
-    explicit LoanEntry(
-        uint256 const& loanID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::loan(loanID), view, j)
-    {
-    }
-};
-
-using RLoanEntry = LoanEntry<ReadView>;
-using WLoanEntry = LoanEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/MPTokenEntry.h

@@ -1,55 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/UintTypes.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class MPTokenEntry : public SLEBase<ViewT, ltMPTOKEN>
-{
-public:
-    using Base = SLEBase<ViewT, ltMPTOKEN>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit MPTokenEntry(
-        MPTID const& issuanceID,
-        AccountID const& holder,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptoken(issuanceID, holder), view, j)
-    {
-    }
-
-    explicit MPTokenEntry(
-        uint256 const& issuanceKey,
-        AccountID const& holder,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptoken(issuanceKey, holder), view, j)
-    {
-    }
-
-    explicit MPTokenEntry(
-        uint256 const& mptokenKey,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptoken(mptokenKey), view, j)
-    {
-    }
-};
-
-using RMPTokenEntry = MPTokenEntry<ReadView>;
-using WMPTokenEntry = MPTokenEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/MPTokenIssuanceEntry.h

@@ -1,56 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/UintTypes.h>
-
-#include <cstdint>
-
-namespace xrpl {
-
-template <typename ViewT>
-class MPTokenIssuanceEntry : public SLEBase<ViewT, ltMPTOKEN_ISSUANCE>
-{
-public:
-    using Base = SLEBase<ViewT, ltMPTOKEN_ISSUANCE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit MPTokenIssuanceEntry(
-        std::uint32_t seq,
-        AccountID const& issuer,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptokenIssuance(makeMptID(seq, issuer)), view, j)
-    {
-    }
-
-    explicit MPTokenIssuanceEntry(
-        MPTID const& issuanceID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptokenIssuance(issuanceID), view, j)
-    {
-    }
-
-    explicit MPTokenIssuanceEntry(
-        uint256 const& issuanceKey,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::mptokenIssuance(issuanceKey), view, j)
-    {
-    }
-};
-
-using RMPTokenIssuanceEntry = MPTokenIssuanceEntry<ReadView>;
-using WMPTokenIssuanceEntry = MPTokenIssuanceEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/NFTokenOfferEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class NFTokenOfferEntry : public SLEBase<ViewT, ltNFTOKEN_OFFER>
-{
-public:
-    using Base = SLEBase<ViewT, ltNFTOKEN_OFFER>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit NFTokenOfferEntry(
-        AccountID const& owner,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::nftokenOffer(owner, seq), view, j)
-    {
-    }
-
-    explicit NFTokenOfferEntry(
-        uint256 const& offerID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::nftokenOffer(offerID), view, j)
-    {
-    }
-};
-
-using RNFTokenOfferEntry = NFTokenOfferEntry<ReadView>;
-using WNFTokenOfferEntry = NFTokenOfferEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/NFTokenPageEntry.h

@@ -1,37 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/Keylet.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class NFTokenPageEntry : public SLEBase<ViewT, ltNFTOKEN_PAGE>
-{
-public:
-    using Base = SLEBase<ViewT, ltNFTOKEN_PAGE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit NFTokenPageEntry(
-        Keylet const& page,
-        uint256 const& token,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::nftokenPage(page, token), view, j)
-    {
-    }
-};
-
-using RNFTokenPageEntry = NFTokenPageEntry<ReadView>;
-using WNFTokenPageEntry = NFTokenPageEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/NegativeUNLEntry.h

@@ -1,33 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class NegativeUNLEntry : public SLEBase<ViewT, ltNEGATIVE_UNL>
-{
-public:
-    using Base = SLEBase<ViewT, ltNEGATIVE_UNL>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit NegativeUNLEntry(
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::negativeUNL(), view, j)
-    {
-    }
-};
-
-using RNegativeUNLEntry = NegativeUNLEntry<ReadView>;
-using WNegativeUNLEntry = NegativeUNLEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/OfferEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class OfferEntry : public SLEBase<ViewT, ltOFFER>
-{
-public:
-    using Base = SLEBase<ViewT, ltOFFER>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit OfferEntry(
-        AccountID const& id,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::offer(id, seq), view, j)
-    {
-    }
-
-    explicit OfferEntry(
-        uint256 const& offerID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::offer(offerID), view, j)
-    {
-    }
-};
-
-using ROfferEntry = OfferEntry<ReadView>;
-using WOfferEntry = OfferEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/OracleEntry.h

@@ -1,38 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-#include <cstdint>
-
-namespace xrpl {
-
-template <typename ViewT>
-class OracleEntry : public SLEBase<ViewT, ltORACLE>
-{
-public:
-    using Base = SLEBase<ViewT, ltORACLE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit OracleEntry(
-        AccountID const& account,
-        std::uint32_t documentID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::oracle(account, documentID), view, j)
-    {
-    }
-};
-
-using ROracleEntry = OracleEntry<ReadView>;
-using WOracleEntry = OracleEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/PayChannelEntry.h

@@ -1,38 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class PayChannelEntry : public SLEBase<ViewT, ltPAYCHAN>
-{
-public:
-    using Base = SLEBase<ViewT, ltPAYCHAN>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit PayChannelEntry(
-        AccountID const& src,
-        AccountID const& dst,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::payChannel(src, dst, seq), view, j)
-    {
-    }
-};
-
-using RPayChannelEntry = PayChannelEntry<ReadView>;
-using WPayChannelEntry = PayChannelEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/PermissionedDomainEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class PermissionedDomainEntry : public SLEBase<ViewT, ltPERMISSIONED_DOMAIN>
-{
-public:
-    using Base = SLEBase<ViewT, ltPERMISSIONED_DOMAIN>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit PermissionedDomainEntry(
-        AccountID const& account,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::permissionedDomain(account, seq), view, j)
-    {
-    }
-
-    explicit PermissionedDomainEntry(
-        uint256 const& domainID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::permissionedDomain(domainID), view, j)
-    {
-    }
-};
-
-using RPermissionedDomainEntry = PermissionedDomainEntry<ReadView>;
-using WPermissionedDomainEntry = PermissionedDomainEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/RippleStateEntry.h

@@ -1,48 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/Issue.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/UintTypes.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class RippleStateEntry : public SLEBase<ViewT, ltRIPPLE_STATE>
-{
-public:
-    using Base = SLEBase<ViewT, ltRIPPLE_STATE>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit RippleStateEntry(
-        AccountID const& id0,
-        AccountID const& id1,
-        Currency const& currency,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::trustLine(id0, id1, currency), view, j)
-    {
-    }
-
-    explicit RippleStateEntry(
-        AccountID const& id,
-        Issue const& issue,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::trustLine(id, issue), view, j)
-    {
-    }
-};
-
-using RRippleStateEntry = RippleStateEntry<ReadView>;
-using WRippleStateEntry = RippleStateEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/SLEBase.h

@@ -1,493 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/basics/contract.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/beast/utility/instrumentation.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/protocol/Keylet.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/STLedgerEntry.h>
-
-#include <concepts>
-#include <memory>
-#include <stdexcept>
-#include <type_traits>
-#include <utility>
-
-namespace xrpl {
-
-// Concept to distinguish read-only vs writable view types
-template <typename V>
-concept WritableView = std::derived_from<V, ApplyView>;
-
-namespace detail {
-
-/**
- * Resolves a keylet for a read-only entry.
- *
- * ReadView::read() on an ApplyView returns the underlying ledger's entry
- * whenever the view is not already tracking one, while peek() installs the
- * view's own copy and returns that. A read-only entry built with read()
- * would therefore hold an SLE that goes stale the moment anything peeks the
- * same key and modifies it. Resolve through peek() whenever the view really is
- * an ApplyView, so every entry over that view shares one SLE.
- *
- * @note The const_cast is what makes reaching ApplyView::peek() possible, and
- *       it is safe only because xrpld never instantiates a ReadView as a
- *       genuinely const object -- every view is a non-const object that some
- *       call sites merely observe through a const reference. If an actually
- *       const-qualified view type is ever introduced (an immutable snapshot,
- *       say), this becomes undefined behavior and must be revisited.
- *
- * @note Consequently a "read-only" entry over an ApplyView is not free of
- *       side effects: peek() installs an Action::Cache entry in the apply
- *       state table. That is benign for transaction metadata -- Cache entries
- *       are skipped in ApplyStateTable::apply(), ::visit() and in metadata
- *       generation -- but it does cost one deep SLE copy on first touch.
- */
-inline SLE::const_pointer
-resolveEntry(ReadView const& view, Keylet const& key)
-{
-    // Views are never const objects; the read-only entry only holds a const
-    // reference because it does not itself modify the view.
-    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
-    if (auto const applyView = dynamic_cast<ApplyView*>(const_cast<ReadView*>(&view)))
-        return applyView->peek(key);
-    return view.read(key);
-}
-
-}  // namespace detail
-
-/**
- * View-parameterized base class for all ledger entries.
- *
- * SLEBase<ReadView>  — read-only:  holds shared_ptr<SLE const> + ReadView const&
- * SLEBase<ApplyView> — writable:   holds shared_ptr<SLE> + ApplyView& + Keylet,
- *                                   plus insert/update/erase operations
- *
- * Write-only members are gated by `requires` clauses, providing compile-time
- * guarantees that read-only entries cannot mutate state.
- *
- * @tparam EntryType the ledger entry type this entry is statically bound to.
- * Derived per-type entries pass their own type (e.g. ltACCOUNT_ROOT); the
- * generic ReadOnlySLE / WritableSLE aliases leave it at ltANY, which opts out
- * of the static type check. Binding the type here is what keeps an entry for
- * one entry type from being constructed or converted from another -- see the
- * converting constructor below.
- *
- * Derived classes should provide domain-specific accessors that hide
- * implementation details of the underlying ledger entry format.
- */
-template <typename ViewT, LedgerEntryType EntryType = ltANY>
-class SLEBase
-{
-public:
-    static constexpr bool kIsWritable = WritableView<ViewT>;
-
-    // The ledger entry type this entry is bound to, and whether that binding
-    // is meaningful (ltANY means "any type", i.e. no static check).
-    static constexpr LedgerEntryType kEntryType = EntryType;
-    static constexpr bool kIsTyped = (EntryType != ltANY);
-
-    // SLE pointer type: mutable for writable views, const for read-only
-    using sle_ptr_type = std::conditional_t<kIsWritable, SLE::pointer, SLE::const_pointer>;
-
-    // View reference type: ApplyView& for writable, ReadView const& for
-    // read-only
-    using view_ref_type = std::conditional_t<kIsWritable, ApplyView&, ReadView const&>;
-
-    // Non-virtual by design: these entries are parameterized on the view and
-    // entry type, never used polymorphically through a base pointer. A vptr
-    // would be 8 bytes of pure overhead on a type meant to be as cheap as the
-    // shared_ptr it wraps. See the static_assert below the class.
-    //
-    // The destructor is public because the ReadOnlySLE / WritableSLE aliases
-    // name this class directly and are used as value types. Since it is not
-    // virtual, never delete a derived entry through an SLEBase*.
-    ~SLEBase() = default;
-
-    SLEBase(SLEBase const&) = default;
-    SLEBase(SLEBase&&) = default;
-    SLEBase&
-    operator=(SLEBase const&) = delete;
-    SLEBase&
-    operator=(SLEBase&&) = delete;
-    SLEBase() = delete;
-
-    // --- Constructors that adopt/resolve an SLE (public so the ReadOnlySLE /
-    //     WritableSLE aliases and the per-type entries can be built directly
-    //     from a keylet, or -- read-only only -- from an already-fetched
-    //     SLE). ---
-
-    /**
-     * Constructor for read-only context (adopt an already-fetched SLE).
-     *
-     * There is deliberately no writable equivalent: a writable entry needs
-     * a Keylet so that newSLE() can still build an entry when none exists,
-     * and that cannot be recovered from a null SLE.
-     */
-    explicit SLEBase(
-        SLE::const_pointer sle,
-        view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        requires(!kIsWritable)
-        : view_(view), sle_(std::move(sle)), j_(j)
-    {
-        XRPL_ASSERT(
-            !kIsTyped || !sle_ || sle_->getType() == kEntryType,
-            "xrpl::SLEBase::SLEBase : adopted SLE matches bound entry type");
-    }
-
-    /**
-     * Constructor for read-only context (read from view by keylet)
-     */
-    explicit SLEBase(
-        Keylet const& key,
-        view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        requires(!kIsWritable)
-        : view_(view), sle_(detail::resolveEntry(view, key)), j_(j)
-    {
-        XRPL_ASSERT(
-            !kIsTyped || key.type == kEntryType,
-            "xrpl::SLEBase::SLEBase : keylet matches bound entry type");
-    }
-
-    /**
-     * Converting constructor: writable → read-only.
-     *
-     * Enables implicit conversion from SLEBase<ApplyView> to
-     * SLEBase<ReadView>, so functions taking ReadOnlySLE const& can accept
-     * WritableSLE.
-     *
-     * Constrained to the same entry type (or to a ltANY target, i.e. widening
-     * a typed entry to a generic ReadOnlySLE). The constraint is load-bearing:
-     * this constructor is inherited into every per-type entry, and unconstrained
-     * it would bind any writable entry that slices to SLEBase, so a WOfferEntry
-     * would convert to an RAccountRootEntry with no cast at the call site.
-     */
-    template <typename OtherViewT, LedgerEntryType OtherType>
-    SLEBase(SLEBase<OtherViewT, OtherType> const& other)
-        requires(!kIsWritable && WritableView<OtherViewT> &&
-                 (OtherType == EntryType || EntryType == ltANY))
-        : view_(other.readView()), sle_(other.rawSle()), j_(other.journal())
-    {
-    }
-
-    /**
-     * Constructor for writable context (peek from view by keylet)
-     */
-    explicit SLEBase(
-        Keylet const& key,
-        ApplyView& view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        requires kIsWritable
-        : view_(view), key_(key), sle_(view_.peek(key)), j_(j)
-    {
-        XRPL_ASSERT(
-            !kIsTyped || key.type == kEntryType,
-            "xrpl::SLEBase::SLEBase : keylet matches bound entry type");
-    }
-
-    /**
-     * Constructor for writable context, for call sites that hold an
-     * ApplyViewContext (peek from ctx.view by keylet).
-     *
-     * ctx.tx is not retained: this exists purely so transactors can pass the
-     * context they already have instead of spelling out ctx.view. If an entry
-     * ever needs the applying transaction, store it here rather than adding
-     * another overload.
-     */
-    explicit SLEBase(
-        Keylet const& key,
-        ApplyViewContext const& ctx,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        requires kIsWritable
-        : SLEBase(key, ctx.view, j)
-    {
-    }
-
-    // --- Common interface (always available) ---
-
-    /**
-     * Returns true if the ledger entry exists
-     */
-    [[nodiscard]] bool
-    exists() const
-    {
-        return sle_ != nullptr;
-    }
-
-    /**
-     * Explicit conversion to bool for convenient existence checking
-     */
-    explicit
-    operator bool() const
-    {
-        return exists();
-    }
-
-    /**
-     * Returns the underlying SLE for read access.
-     *
-     * Prefer operator-> / operator* for field access; this is for the call
-     * sites that need the shared_ptr itself.
-     */
-    [[nodiscard]] SLE::const_pointer
-    rawSle() const
-    {
-        return sle_;
-    }
-
-    /**
-     * Returns the ledger entry type of this entry.
-     *
-     * For a per-type entry this is kEntryType, known at compile time and
-     * valid whether or not the entry exists. Only the generic ReadOnlySLE /
-     * WritableSLE aliases have to read it back out of the SLE.
-     *
-     * @throws std::logic_error for a generic (ltANY) entry if exists() is
-     *         false.
-     */
-    [[nodiscard]] LedgerEntryType
-    type() const
-    {
-        if constexpr (kIsTyped)
-        {
-            return kEntryType;
-        }
-        else
-        {
-            if (!exists())
-                Throw<std::logic_error>("xrpl::SLEBase::type : entry does not exist");
-            return sle_->getType();
-        }
-    }
-
-    /**
-     * Returns the keylet identifying this entry.
-     *
-     * Writable entries keep the keylet they were built from, so it is valid
-     * even before newSLE(). Read-only entries derive it from the SLE, which
-     * must therefore exist.
-     *
-     * @throws std::logic_error for a read-only entry if exists() is false.
-     */
-    [[nodiscard]] Keylet
-    keylet() const
-    {
-        if constexpr (kIsWritable)
-        {
-            return key_;
-        }
-        else
-        {
-            if (!exists())
-                Throw<std::logic_error>("xrpl::SLEBase::keylet : entry does not exist");
-            // Take the type from the SLE, not from kEntryType: the adopt-SLE
-            // constructor's type check is assert-only, so a Release build can
-            // be holding an SLE whose type disagrees with the binding, and the
-            // SLE is the one telling the truth.
-            return Keylet(sle_->getType(), sle_->key());
-        }
-    }
-
-    /**
-     * Returns the ledger key of this entry.
-     *
-     * @throws std::logic_error same as keylet(): for read-only entries,
-     *         if exists() is false.
-     */
-    [[nodiscard]] uint256
-    key() const
-    {
-        return keylet().key;
-    }
-
-    /**
-     * Returns the read view (always available; ApplyView inherits ReadView)
-     */
-    [[nodiscard]] ReadView const&
-    readView() const
-    {
-        return view_;
-    }
-
-    /**
-     * Const dereference operators (always available)
-     *
-     * @throws std::logic_error if exists() is false.
-     */
-    STLedgerEntry const*
-    operator->() const
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::operator-> : entry does not exist");
-        return sle_.get();
-    }
-
-    STLedgerEntry const&
-    operator*() const
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::operator* : entry does not exist");
-        return *sle_;
-    }
-
-    // --- Writable interface (compile-time gated) ---
-    //
-    // Everything that hands out mutable access (or mutates) is non-const, so
-    // that a `WFooEntry const&` is as inert as a `RFooEntry`. Use readView()
-    // when a const entry only needs to inspect the view.
-
-    /**
-     * Returns the underlying SLE for write access.
-     *
-     * Prefer operator-> / operator* for field access; this is for the call
-     * sites that need the shared_ptr itself.
-     */
-    [[nodiscard]] sle_ptr_type const&
-    mutableRawSle()
-        requires kIsWritable
-    {
-        return sle_;
-    }
-
-    /**
-     * Returns the apply view for write operations
-     */
-    [[nodiscard]] ApplyView&
-    applyView()
-        requires kIsWritable
-    {
-        return view_;
-    }
-
-    /**
-     * Mutable dereference operators
-     *
-     * @throws std::logic_error if exists() is false.
-     */
-    STLedgerEntry*
-    operator->()
-        requires kIsWritable
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::operator-> : entry does not exist");
-        return sle_.get();
-    }
-
-    STLedgerEntry&
-    operator*()
-        requires kIsWritable
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::operator* : entry does not exist");
-        return *sle_;
-    }
-
-    /**
-     * Inserts the entry into the view.
-     *
-     * @throws std::logic_error if exists() is false.
-     */
-    void
-    insert()
-        requires kIsWritable
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::insert : entry does not exist");
-        view_.insert(sle_);
-    }
-
-    /**
-     * Erases the entry from the view.
-     *
-     * Drops the SLE afterwards, so the entry reports !exists() and any
-     * further use trips an assertion here rather than either throwing from
-     * deep inside ApplyStateTable or -- worse -- silently succeeding. For an
-     * entry that already existed, ApplyStateTable::erase keeps holding this
-     * exact SLE and builds the DeletedNode's FinalFields from it, so a write
-     * through the entry after erase() would land in transaction metadata
-     * with no diagnostic at all.
-     *
-     * @throws std::logic_error if exists() is false.
-     */
-    void
-    erase()
-        requires kIsWritable
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::erase : entry does not exist");
-        view_.erase(sle_);
-        sle_ = nullptr;
-    }
-
-    /**
-     * @throws std::logic_error if exists() is false.
-     */
-    void
-    update()
-        requires kIsWritable
-    {
-        if (!exists())
-            Throw<std::logic_error>("xrpl::SLEBase::update : entry does not exist");
-        view_.update(sle_);
-    }
-
-    /**
-     * @throws std::logic_error if exists() is true: newSLE() would otherwise
-     *         silently discard the SLE already held.
-     */
-    void
-    newSLE()
-        requires kIsWritable
-    {
-        if (exists())
-            Throw<std::logic_error>("xrpl::SLEBase::newSLE : entry already exists");
-        sle_ = std::make_shared<SLE>(key_);
-    }
-
-    [[nodiscard]] beast::Journal
-    journal() const
-    {
-        return j_;
-    }
-
-protected:
-    view_ref_type view_;
-
-    // Keylet is only meaningful for writable views, which need it to build an
-    // SLE that does not exist yet; read-only entries derive it from the SLE.
-    struct Empty
-    {
-    };
-    // No default member initializer: Keylet is not default-constructible, so
-    // every writable constructor must initialize key_ explicitly.
-    [[no_unique_address]]
-    std::conditional_t<kIsWritable, Keylet, Empty> key_;
-
-    sle_ptr_type sle_{};
-    beast::Journal j_;
-};
-
-/**
- * Generic (any-entry-type) SLE entries.
- *
- * Use these when the concrete ledger entry type is not known at a given site;
- * otherwise prefer the per-type entries (e.g. AccountRootEntry.h), which
- * additionally enforce the entry type at compile time.
- *
- *   SLE::const_pointer / SLE::const_ref  ->  ReadOnlySLE
- *   SLE::pointer       / SLE::ref        ->  WritableSLE
- */
-using ReadOnlySLE = SLEBase<ReadView>;
-using WritableSLE = SLEBase<ApplyView>;
-
-static_assert(
-    !std::is_polymorphic_v<ReadOnlySLE> && !std::is_polymorphic_v<WritableSLE>,
-    "SLEBase must stay a thin value type; it must not acquire a vtable");
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/SignerListEntry.h

@@ -1,35 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class SignerListEntry : public SLEBase<ViewT, ltSIGNER_LIST>
-{
-public:
-    using Base = SLEBase<ViewT, ltSIGNER_LIST>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit SignerListEntry(
-        AccountID const& account,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::signerList(account), view, j)
-    {
-    }
-};
-
-using RSignerListEntry = SignerListEntry<ReadView>;
-using WSignerListEntry = SignerListEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/SponsorshipEntry.h

@@ -1,36 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class SponsorshipEntry : public SLEBase<ViewT, ltSPONSORSHIP>
-{
-public:
-    using Base = SLEBase<ViewT, ltSPONSORSHIP>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit SponsorshipEntry(
-        AccountID const& sponsor,
-        AccountID const& sponsee,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::sponsorship(sponsor, sponsee), view, j)
-    {
-    }
-};
-
-using RSponsorshipEntry = SponsorshipEntry<ReadView>;
-using WSponsorshipEntry = SponsorshipEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/TicketEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class TicketEntry : public SLEBase<ViewT, ltTICKET>
-{
-public:
-    using Base = SLEBase<ViewT, ltTICKET>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit TicketEntry(
-        AccountID const& id,
-        SeqProxy const& ticketSeq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::ticket(id, ticketSeq), view, j)
-    {
-    }
-
-    explicit TicketEntry(
-        uint256 const& ticketID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::ticket(ticketID), view, j)
-    {
-    }
-};
-
-using RTicketEntry = TicketEntry<ReadView>;
-using WTicketEntry = TicketEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/VaultEntry.h

@@ -1,46 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/AccountID.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/SeqProxy.h>
-
-namespace xrpl {
-
-template <typename ViewT>
-class VaultEntry : public SLEBase<ViewT, ltVAULT>
-{
-public:
-    using Base = SLEBase<ViewT, ltVAULT>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit VaultEntry(
-        AccountID const& owner,
-        SeqProxy const& seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::vault(owner, seq), view, j)
-    {
-    }
-
-    explicit VaultEntry(
-        uint256 const& vaultID,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::vault(vaultID), view, j)
-    {
-    }
-};
-
-using RVaultEntry = VaultEntry<ReadView>;
-using WVaultEntry = VaultEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/XChainOwnedClaimIDEntry.h

@@ -1,38 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/STXChainBridge.h>
-
-#include <cstdint>
-
-namespace xrpl {
-
-template <typename ViewT>
-class XChainOwnedClaimIDEntry : public SLEBase<ViewT, ltXCHAIN_OWNED_CLAIM_ID>
-{
-public:
-    using Base = SLEBase<ViewT, ltXCHAIN_OWNED_CLAIM_ID>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit XChainOwnedClaimIDEntry(
-        STXChainBridge const& bridge,
-        std::uint64_t seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::xChainClaimID(bridge, seq), view, j)
-    {
-    }
-};
-
-using RXChainOwnedClaimIDEntry = XChainOwnedClaimIDEntry<ReadView>;
-using WXChainOwnedClaimIDEntry = XChainOwnedClaimIDEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/ledger/helpers/XChainOwnedCreateAccountClaimIDEntry.h

@@ -1,39 +0,0 @@
-#pragma once
-
-#include <xrpl/beast/utility/Journal.h>
-#include <xrpl/ledger/ApplyView.h>
-#include <xrpl/ledger/ReadView.h>
-#include <xrpl/ledger/helpers/SLEBase.h>
-#include <xrpl/protocol/Indexes.h>
-#include <xrpl/protocol/LedgerFormats.h>
-#include <xrpl/protocol/STXChainBridge.h>
-
-#include <cstdint>
-
-namespace xrpl {
-
-template <typename ViewT>
-class XChainOwnedCreateAccountClaimIDEntry
-    : public SLEBase<ViewT, ltXCHAIN_OWNED_CREATE_ACCOUNT_CLAIM_ID>
-{
-public:
-    using Base = SLEBase<ViewT, ltXCHAIN_OWNED_CREATE_ACCOUNT_CLAIM_ID>;
-
-    // Inherit base constructors: adopt an existing SLE, or resolve one from a
-    // Keylet against the view.
-    using Base::Base;
-
-    explicit XChainOwnedCreateAccountClaimIDEntry(
-        STXChainBridge const& bridge,
-        std::uint64_t seq,
-        Base::view_ref_type view,
-        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
-        : Base(keylet::xChainCreateAccountClaimID(bridge, seq), view, j)
-    {
-    }
-};
-
-using RXChainOwnedCreateAccountClaimIDEntry = XChainOwnedCreateAccountClaimIDEntry<ReadView>;
-using WXChainOwnedCreateAccountClaimIDEntry = XChainOwnedCreateAccountClaimIDEntry<ApplyView>;
-
-}  // namespace xrpl

include/xrpl/protocol/AMMCore.h

@@ -91,17 +91,6 @@ getFee(std::uint16_t tfee)
     return Number{tfee} / kAuctionSlotFeeScaleFactor;
 }
 
-/**
- * Minimum auction slot price: LPTokens * TradingFee / kAuctionSlotMinFeeFraction
- * @param lptAMMBalance  AMM LP token balance
- * @param tradingFee     trading fee in {0, 1000}
- */
-inline Number
-ammAuctionMinSlotPrice(Number const& lptAMMBalance, std::uint16_t tradingFee)
-{
-    return lptAMMBalance * getFee(tradingFee) / kAuctionSlotMinFeeFraction;
-}
-
 /**
  * Get fee multiplier (1 - tfee)
  * @tfee trading fee in basis points

include/xrpl/protocol/Permissions.h

@@ -4,7 +4,6 @@
 #include <xrpl/protocol/Rules.h>
 #include <xrpl/protocol/SOTemplate.h>
 #include <xrpl/protocol/TxFormats.h>
-#include <xrpl/protocol/TxSettings.h>
 
 #include <cstdint>
 #include <functional>
@@ -39,6 +38,11 @@ enum GranularPermissionType : std::uint32_t {
 #pragma pop_macro("GRANULAR_PERMISSION")
 };
 
+// Injected bare enumerators (xrpl::delegable / xrpl::notDelegable) are required by preprocessor
+// tricks in tests and macro-generated code; enum class would break that.
+// NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
+enum Delegation { Delegable, NotDelegable };
+
 class Permission
 {
 private:
@@ -61,7 +65,7 @@ private:
     struct TxDelegationEntry
     {
         uint256 amendment;
-        Delegation delegable{Delegation::NotDelegable};
+        Delegation delegable{NotDelegable};
     };
 
     std::unordered_set<TxType> granularTxTypes_;

include/xrpl/protocol/Protocol.h

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

include/xrpl/protocol/TER.h

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

include/xrpl/protocol/TxSettings.h

@@ -1,96 +0,0 @@
-#pragma once
-
-#include <xrpl/basics/base_uint.h>
-#include <xrpl/basics/safe_cast.h>
-
-#include <cstdint>
-#include <type_traits>
-
-namespace xrpl {
-
-enum class Delegation { Delegable, NotDelegable };
-
-/**
- * Operations a transaction is permitted to perform, as a bitfield.
- *
- * These are declared per-transaction in transactions.macro (via
- * TxSettings::privileges) and enforced in InvariantCheck.cpp.
- */
-enum class Privilege : std::uint16_t {
-    NoPriv = 0x0000,              // The transaction can not do any of the enumerated operations
-    CreateAcct = 0x0001,          // The transaction can create a new ACCOUNT_ROOT object.
-    CreatePseudoAcct = 0x0002,    // The transaction can create a pseudo account,
-                                  // which implies createAcct
-    MustDeleteAcct = 0x0004,      // The transaction must delete an ACCOUNT_ROOT object
-    MayDeleteAcct = 0x0008,       // The transaction may delete an ACCOUNT_ROOT
-                                  // object, but does not have to
-    OverrideFreeze = 0x0010,      // The transaction can override some freeze rules
-    ChangeNftCounts = 0x0020,     // The transaction can mint or burn an NFT
-    CreateMptIssuance = 0x0040,   // The transaction can create a new MPT issuance
-    DestroyMptIssuance = 0x0080,  // The transaction can destroy an MPT issuance
-    MustAuthorizeMpt = 0x0100,    // The transaction MUST create or delete an MPT
-                                  // object (except by issuer)
-    MayAuthorizeMpt = 0x0200,     // The transaction MAY create or delete an MPT
-                                  // object (except by issuer)
-    MayDeleteMpt = 0x0400,        // The transaction MAY delete an MPT object. May not create.
-    MustModifyVault = 0x0800,     // The transaction must modify, delete or create, a vault
-    MayModifyVault = 0x1000,      // The transaction MAY modify, delete or create, a vault
-    MayCreateMpt = 0x2000,        // The transaction MAY create an MPT object, except for issuer.
-};
-
-// The inner static_cast is not redundant: the underlying type is narrower than
-// `int`, so the operands integer-promote and the result has to be narrowed back.
-// safeCast rejects that narrowing, but every input bit is a Privilege bit by
-// construction, so the result is always representable.
-constexpr Privilege
-operator|(Privilege lhs, Privilege rhs)
-{
-    using Underlying = std::underlying_type_t<Privilege>;
-    return static_cast<Privilege>(
-        static_cast<Underlying>(safeCast<Underlying>(lhs) | safeCast<Underlying>(rhs)));
-}
-
-constexpr Privilege
-operator&(Privilege lhs, Privilege rhs)
-{
-    using Underlying = std::underlying_type_t<Privilege>;
-    return static_cast<Privilege>(
-        static_cast<Underlying>(safeCast<Underlying>(lhs) & safeCast<Underlying>(rhs)));
-}
-
-/**
- * Per-transaction metadata declared in transactions.macro.
- *
- * Every member has a default, so a transaction only needs to name the settings
- * that differ from the common case. See the documentation at the top of
- * transactions.macro for the authoring syntax.
- *
- * This is deliberately not a constexpr-friendly type: amendment identifiers are
- * runtime-initialized `extern uint256 const` globals (see Feature.h), so a
- * TxSettings can only be built at runtime.
- */
-struct TxSettings
-{
-    /**
-     * Whether an account may delegate this transaction to another account.
-     */
-    Delegation delegable{Delegation::NotDelegable};
-
-    /**
-     * The amendment gating this transaction, or uint256{} if always available.
-     */
-    // The `{}` looks redundant, because BaseUInt's default constructor already
-    // zeroes the value. It is not: without a default member initializer here,
-    // every partial designated initializer in transactions.macro trips the
-    // missing-designated-field-initializers warning, which the build treats as
-    // an error.
-    // NOLINTNEXTLINE(readability-redundant-member-init)
-    uint256 amendment{};
-
-    /**
-     * Operations this transaction is permitted to perform.
-     */
-    Privilege privileges{Privilege::NoPriv};
-};
-
-}  // namespace xrpl

include/xrpl/protocol_autogen/transactions/AMMBid.h

@@ -21,7 +21,7 @@ class AMMBidBuilder;
  * Type: ttAMM_BID (39)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMBidBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMClawback.h

@@ -21,7 +21,7 @@ class AMMClawbackBuilder;
  * Type: ttAMM_CLAWBACK (31)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMMClawback
- * Privileges: Privilege::MayDeleteAcct | Privilege::OverrideFreeze | Privilege::MayAuthorizeMpt
+ * Privileges: MayDeleteAcct | OverrideFreeze | MayAuthorizeMpt
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMClawbackBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMCreate.h

@@ -21,7 +21,7 @@ class AMMCreateBuilder;
  * Type: ttAMM_CREATE (35)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::CreatePseudoAcct | Privilege::MayCreateMpt
+ * Privileges: CreatePseudoAcct | MayCreateMpt
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMCreateBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMDelete.h

@@ -21,7 +21,7 @@ class AMMDeleteBuilder;
  * Type: ttAMM_DELETE (40)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::MustDeleteAcct | Privilege::MayDeleteMpt
+ * Privileges: MustDeleteAcct | MayDeleteMpt
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMDeleteBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMDeposit.h

@@ -21,7 +21,7 @@ class AMMDepositBuilder;
  * Type: ttAMM_DEPOSIT (36)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMDepositBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMVote.h

@@ -21,7 +21,7 @@ class AMMVoteBuilder;
  * Type: ttAMM_VOTE (38)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMVoteBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AMMWithdraw.h

@@ -21,7 +21,7 @@ class AMMWithdrawBuilder;
  * Type: ttAMM_WITHDRAW (37)
  * Delegable: Delegation::Delegable
  * Amendment: featureAMM
- * Privileges: Privilege::MayDeleteAcct | Privilege::MayAuthorizeMpt
+ * Privileges: MayDeleteAcct | MayAuthorizeMpt
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AMMWithdrawBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AccountDelete.h

@@ -21,7 +21,7 @@ class AccountDeleteBuilder;
  * Type: ttACCOUNT_DELETE (21)
  * Delegable: Delegation::NotDelegable
  * Amendment: uint256{}
- * Privileges: Privilege::MustDeleteAcct
+ * Privileges: MustDeleteAcct
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AccountDeleteBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/AccountSet.h

@@ -21,7 +21,7 @@ class AccountSetBuilder;
  * Type: ttACCOUNT_SET (3)
  * Delegable: Delegation::NotDelegable
  * Amendment: uint256{}
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use AccountSetBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/Batch.h

@@ -21,7 +21,7 @@ class BatchBuilder;
  * Type: ttBATCH (71)
  * Delegable: Delegation::NotDelegable
  * Amendment: featureBatchV1_1
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use BatchBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/CheckCancel.h

@@ -21,7 +21,7 @@ class CheckCancelBuilder;
  * Type: ttCHECK_CANCEL (18)
  * Delegable: Delegation::Delegable
  * Amendment: uint256{}
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use CheckCancelBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/CheckCash.h

@@ -21,7 +21,7 @@ class CheckCashBuilder;
  * Type: ttCHECK_CASH (17)
  * Delegable: Delegation::Delegable
  * Amendment: uint256{}
- * Privileges: Privilege::MayCreateMpt
+ * Privileges: MayCreateMpt
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use CheckCashBuilder to construct new transactions.

include/xrpl/protocol_autogen/transactions/CheckCreate.h

@@ -21,7 +21,7 @@ class CheckCreateBuilder;
  * Type: ttCHECK_CREATE (16)
  * Delegable: Delegation::Delegable
  * Amendment: uint256{}
- * Privileges: Privilege::NoPriv
+ * Privileges: NoPriv
  *
  * Immutable wrapper around STTx providing type-safe field access.
  * Use CheckCreateBuilder to construct new transactions.