refactor: Wasm vm redesign by kuznetsss · Pull Request #7952 · XRPLF/rippled

kuznetsss · 2026-08-04T15:21:58Z

High Level Overview of Change

This PR replaces the wasmi C-API integration with a Rust wasmi wrapper reached over a cxx
bridge.

What's here

crates/ — cargo workspace, built in via corrosion.

xrpl-host-functions — the ABI's single declaration site. host_functions! { … }
generates the HostFunctions trait and the spec enum (import name + gas per function).
no_std, no allocator, zero runtime deps, builds for wasm32 — so the guest SDK can
implement the same trait from the same declaration.
xrpl-wasm-vm — the engine: run, and check (compile / imports / entry point /
declared memory, with no host, store or gas, because a transaction's preflight() has no
ledger to serve a host call from).
xrpl-wasm-vm-ffi — the bridge. Three crossings: run_escrow in, host calls back out,
check_escrow in.
xrpl-wasm-testkit — test-only compile_wat, a separate crate so no assembler can reach
the shipped node.

C++ — HostContext.{h,cpp}, an ABI-shaped noexcept view of HostFunctions; and
WasmVM.{h,cpp} with runEscrowWasm / preflightEscrowWasm and both TER maps.

Not in this PR

5 of ~65 host functions are registered (ldgr_index, home_le_field, sha512_half,
trace, trace_num). The remaining HostFuncImpl*.cpp are untouched and still compile.
src/test/app/HostFuncImpl_test.cpp is commented out: its assertions ran through the
deleted C lowering.

Base branches

The PR is based on 2 branches:

Context of Change

API Impact

Public API: New feature (new methods and/or new fields)
Public API: Breaking change (in general, breaking changes should only impact the next api_version)
libxrpl change (any change that may affect libxrpl or dependents of libxrpl)
Peer protocol change (must be backward compatible or bump the peer protocol version)

chore: Fix clang version in devshell

TimothyBanks · 2026-08-05T17:27:34Z

+    // non-positive limit means is a transaction-validity rule; the engine's own budget is
+    // therefore an unsigned quantity with no invalid value to represent.
+    if (gasLimit <= 0)
+        return std::unexpected(WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt});


nit:

Suggested change

return std::unexpected(WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt});

return std::unexpected{WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt}};

TimothyBanks · 2026-08-05T17:27:50Z

+    if (gasLimit <= 0)
+        return std::unexpected(WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt});
+
+    auto const nodeSideFault = std::unexpected(WasmTER{.ter = tecINTERNAL, .cost = std::nullopt});


nit:

Suggested change

auto const nodeSideFault = std::unexpected(WasmTER{.ter = tecINTERNAL, .cost = std::nullopt});

auto const nodeSideFault = std::unexpected{WasmTER{.ter = tecINTERNAL, .cost = std::nullopt}};

TimothyBanks · 2026-08-05T17:29:41Z

+        HostContext ctx{hfs};
+        auto const run = rs::wasm_vm::run_escrow(
+            ctx,
+            rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),


nit:

Suggested change

rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),

rust::Slice<std::uint8_t const>{wasmCode.data(), wasmCode.size()},

TimothyBanks · 2026-08-05T17:29:57Z

+            ctx,
+            rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),
+            static_cast<std::uint64_t>(gasLimit),
+            rust::Str(funcName.data(), funcName.size()));


nit:

Suggested change

rust::Str(funcName.data(), funcName.size()));

rust::Str{funcName.data(), funcName.size())};

TimothyBanks · 2026-08-05T17:30:40Z

+        if (!result)
+        {
+            JLOG(hfs.getJournal().warn())
+                << "wasm: " << std::string_view(run.detail.data(), run.detail.size())


nit:

Suggested change

<< "wasm: " << std::string_view(run.detail.data(), run.detail.size())

<< "wasm: " << std::string_view{run.detail.data(), run.detail.size()}

TimothyBanks · 2026-08-05T17:31:13Z

-    return impl_->getJournal();
+    return guarded(j, NotTEC{telFAILED_PROCESSING}, [&]() {
+        auto const checked = rs::wasm_vm::check_escrow(
+            rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),


nit:

Suggested change

rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),

rust::Slice<std::uint8_t const>{wasmCode.data(), wasmCode.size()},

TimothyBanks · 2026-08-05T17:31:45Z

+    return guarded(j, NotTEC{telFAILED_PROCESSING}, [&]() {
+        auto const checked = rs::wasm_vm::check_escrow(
+            rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),
+            rust::Str(funcName.data(), funcName.size()));


nit:

Suggested change

rust::Str(funcName.data(), funcName.size()));

rust::Str{funcName.data(), funcName.size())};

TimothyBanks · 2026-08-05T17:32:14Z

+        if (!isTesSuccess(ter))
+        {
+            JLOG(j.warn()) << "wasm: "
+                           << std::string_view(checked.detail.data(), checked.detail.size())


nit:

Suggested change

<< std::string_view(checked.detail.data(), checked.detail.size())

<< std::string_view{checked.detail.data(), checked.detail.size()}

TimothyBanks · 2026-08-05T17:36:45Z

+// ldgr_index — no input, one scalar output
+// ---------------------------------------------------------------------------------------
+
+class LedgerSqnCall : public HostCallTest


I kind of feel like we should split these tests out into their own source files. There will be a decent amount of host functions and this file will get pretty large.

TimothyBanks · 2026-08-05T17:38:13Z

+// an expectation can say *what* the guest asked the host to work on.
+MATCHER_P(BytesAre, expected, "")
+{
+    return std::string_view(reinterpret_cast<char const*>(arg.data()), arg.size()) ==


nit:

Suggested change

return std::string_view(reinterpret_cast<char const*>(arg.data()), arg.size()) ==

return std::string_view{reinterpret_cast<char const*>(arg.data()), arg.size()} ==

TimothyBanks · 2026-08-05T17:38:26Z

+MATCHER_P(BytesAre, expected, "")
+{
+    return std::string_view(reinterpret_cast<char const*>(arg.data()), arg.size()) ==
+        std::string_view(expected);


nit:

Suggested change

std::string_view(expected);

std::string_view{expected};

TimothyBanks · 2026-08-05T17:41:51Z

+    std::string text_;
+
+public:
+    CapturingSink() : Sink(beast::Severity::Warning, false)


nit:

Suggested change

CapturingSink() : Sink(beast::Severity::Warning, false)

CapturingSink() : Sink{beast::Severity::Warning, false}

TimothyBanks · 2026-08-05T17:48:10Z

+
+// Keeps what a run logged. The host's default journal is a null sink, which would let a
+// swallowed condition pass a test that only checks the TER.
+class CapturingSink : public beast::Journal::Sink


This seems like a type that should already be available within the repo.

There is a CaptureSink in CaptureLogs.h.

TimothyBanks · 2026-08-05T17:49:19Z

+inline Bytes
+assembleWat(std::string_view wat)
+{
+    auto const wasm = rs::wasm_testkit::compile_wat(rust::Str(wat.data(), wat.size()));


nit:

Suggested change

auto const wasm = rs::wasm_testkit::compile_wat(rust::Str(wat.data(), wat.size()));

auto const wasm = rs::wasm_testkit::compile_wat(rust::Str{wat.data(), wat.size()});

TimothyBanks · 2026-08-05T17:50:28Z

+    }
+
+    static Bytes
+    assemble(std::string_view wat)


What does this function provide over just calling assembleWat?

It also converts rust::Vec into Bytes

TimothyBanks · 2026-08-05T17:53:08Z

+        char const* what;
+        Bytes code;
+        std::string_view entryPoint;
+    } const cases[] = {


While this is valid C++ code, it seems like a rarely used way to declare a type and use it in a variable.

TimothyBanks · 2026-08-05T17:53:36Z

+// have screened.
+TEST_F(WasmVMTest, TrappingStartSectionIsChargedToTheContract)
+{
+    constexpr std::string_view wat = R"wat(


nit: All of these wat variables could be static as well.

TimothyBanks · 2026-08-05T17:54:14Z

+// asked to run anything.
+TEST_F(WasmVMTest, NoGasIsRefusedAsMalformedRatherThanRun)
+{
+    for (std::int64_t const gas : {std::int64_t{0}, std::int64_t{-1}})


nit:

Suggested change

for (std::int64_t const gas : {std::int64_t{0}, std::int64_t{-1}})

for (auto const gas : {std::int64_t{0}, std::int64_t{-1}})

TimothyBanks

The pending conversations are all something that can be done at a later time. I think this is a great start so no reason to hold it up from us flushing out the rest of the host functions.

depthfirst-app · 2026-08-07T16:29:30Z

+    SlotsFull = -8,
+    EmptySlot = -9,
+    LedgerObjNotFound = -10,
+    Decoding = -11,


🟡 Severity: MEDIUM

The Rust HostError enum assigns Decoding = -11, but the C++ HostFunctionError in WasmCommon.h assigns OutOfTransferLimit = -11. The doc comment here claims the discriminants "mirror" the C++ enum, but they diverge at this code. When a C++ host function returns error code -11 (meaning OutOfTransferLimit), the Rust engine via HostError::from_code(-11) interprets it as Decoding — a different semantic. Since error codes are consensus-relevant (contracts branch on them), this mismatch can cause incorrect guest behavior or divergence between the two ABI definitions.
Helpful? Add 👍 / 👎

💡 Fix Suggestion

Suggestion: Realign the Rust HostError enum discriminants to match the C++ HostFunctionError enum in WasmCommon.h. Specifically:

In crates/xrpl-host-functions/src/lib.rs, change Decoding = -11 to OutOfTransferLimit = -11 (matching C++ line 37), and move Decoding to a new code beyond the shared C++ range (e.g., -21 or another unused value).

Remove or renumber the current OutOfTransferLimit = -23 (line 86) since it will now be at -11.

Also align Internal = -1 with C++'s Unimplemented = -1 — either rename the Rust variant or add Unimplemented as an alias.

Update the C++ enum in WasmCommon.h to include the Rust-only variants (Decoding, NoRuntime, OutOfGas) so both sides have the same complete set.

Update all downstream uses of these variants:

crates/xrpl-wasm-vm/src/register.rs lines 90 and 107 (uses HostError::Decoding)

crates/xrpl-wasm-vm/src/vm.rs line 232 (matches on HostError::Decoding)

crates/xrpl-wasm-vm/src/abi.rs line 63, 288, 298 (uses HostError::OutOfTransferLimit)

crates/xrpl-host-functions/tests/host_errors.rs lines 32 and 44 (expected code values)

crates/xrpl-wasm-vm/tests/host_calls.rs line 208 and tests/budgets.rs line 311, 331

Update the test comment at src/tests/libxrpl/tx/wasm/WasmVM.cpp:236 that documents the known drift.

depthfirst-app · 2026-08-07T17:06:26Z

+    if (size <= out.size())
+        std::memcpy(out.data(), value, size);
+    return static_cast<std::int32_t>(size);


⚪ Severity: LOW

The answer() helper casts std::size_t to std::int32_t without range check. If a buggy HostFunctions implementation returns a Bytes vector larger than INT32_MAX, this wraps to a negative value, which the Rust engine interprets as a HostError code — causing a misclassified error on a consensus-critical path.
Helpful? Add 👍 / 👎

💡 Fix Suggestion

Suggestion: Add a range check before the static_cast<std::int32_t>(size) to guard against values larger than INT32_MAX. If size exceeds INT32_MAX, return kHostInternal (the existing fatal-error sentinel already defined in this anonymous namespace) instead of allowing the cast to wrap to a negative value. INT32_MAX is available from the already-included <cstdint>.

⚠️ Experimental Feature: This code suggestion is automatically generated. Please review carefully.

Suggested change

if (size <= out.size())

std::memcpy(out.data(), value, size);

return static_cast<std::int32_t>(size);

if (size > static_cast<std::size_t>(INT32_MAX))

return kHostInternal;

if (size <= out.size())

std::memcpy(out.data(), value, size);

return static_cast<std::int32_t>(size);

github-actions · 2026-08-09T18:42:11Z

This PR has conflicts, please resolve them in order for the PR to be reviewed.

kuznetsss added 30 commits April 27, 2026 17:47

Add rust interop PoC

ffc5579

Minor improvements

5fdedd7

More improvements

d009ef2

Try fixing linkage

abb2ef3

Temporarily disable linkage check

8bb8c3b

Try to fix windows

175259d

Another try to fix windows

bc483b2

Add expample of panic handling

5be406e

Merge develop

1dce793

Merge develop

b5990be

Add rust to CI

465fa8e

Merge branch 'develop' into Rust_integration

4277c80

Merge branch 'develop' into Rust_integration

35583fc

Update docker image

aeee77f

Merge develop

012f894

Update CI image hashes

7a3bd8a

Fix build and exclue generated code from clang-tidy

ab97f4b

chore: Fix clang version in devshell

Merge develop

fcf376d

Run pre-commit

45e3d3f

Merge branches

1b52b65

Add empty crates

11fd30b

Remove wasmi dependency

b7059de

Merge branch 'develop' into Rust_integration

55911cf

Update ci image

abcdeab

Merge branch 'develop' into Rust_integration

f458c0f

Implementing macro

7ebd92a

Run pre-commit

7915202

Fix codecov settings

be3d98e

Moved HostFunctionsInput into a separte file

c4ce52c

Finish host function macro

94ed8e2

TimothyBanks reviewed Aug 5, 2026

View reviewed changes

Comment thread src/tests/libxrpl/tx/wasm/MockHostFunctions.h

TimothyBanks reviewed Aug 5, 2026

View reviewed changes

Fixed review comments

7f9ece3

TimothyBanks approved these changes Aug 7, 2026

View reviewed changes

kuznetsss added 2 commits August 7, 2026 16:49

Bring tests back

8f0eff4

Fix build

ba7bf92

depthfirst-app Bot reviewed Aug 7, 2026

View reviewed changes

Fix clang-tidy errors

6bc7a9a

depthfirst-app Bot reviewed Aug 7, 2026

View reviewed changes

github-actions Bot added the PR: has conflicts label Aug 9, 2026

Fix build on windows

b5a90e7

kuznetsss force-pushed the Wasm-vm-redesign branch from eaa7344 to b5a90e7 Compare August 10, 2026 14:41

	return std::unexpected(WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt});
	return std::unexpected{WasmTER{.ter = temBAD_AMOUNT, .cost = std::nullopt}};

	auto const nodeSideFault = std::unexpected(WasmTER{.ter = tecINTERNAL, .cost = std::nullopt});
	auto const nodeSideFault = std::unexpected{WasmTER{.ter = tecINTERNAL, .cost = std::nullopt}};

	rust::Slice<std::uint8_t const>(wasmCode.data(), wasmCode.size()),
	rust::Slice<std::uint8_t const>{wasmCode.data(), wasmCode.size()},

	rust::Str(funcName.data(), funcName.size()));
	rust::Str{funcName.data(), funcName.size())};

	<< "wasm: " << std::string_view(run.detail.data(), run.detail.size())
	<< "wasm: " << std::string_view{run.detail.data(), run.detail.size()}

	<< std::string_view(checked.detail.data(), checked.detail.size())
	<< std::string_view{checked.detail.data(), checked.detail.size()}

	return std::string_view(reinterpret_cast<char const*>(arg.data()), arg.size()) ==
	return std::string_view{reinterpret_cast<char const*>(arg.data()), arg.size()} ==

	CapturingSink() : Sink(beast::Severity::Warning, false)
	CapturingSink() : Sink{beast::Severity::Warning, false}

	auto const wasm = rs::wasm_testkit::compile_wat(rust::Str(wat.data(), wat.size()));
	auto const wasm = rs::wasm_testkit::compile_wat(rust::Str{wat.data(), wat.size()});

	for (std::int64_t const gas : {std::int64_t{0}, std::int64_t{-1}})
	for (auto const gas : {std::int64_t{0}, std::int64_t{-1}})

Uh oh!

Conversation

kuznetsss commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

High Level Overview of Change

What's here

Not in this PR

Base branches

Context of Change

API Impact

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TimothyBanks Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TimothyBanks left a comment

Choose a reason for hiding this comment

Uh oh!

depthfirst-app Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

depthfirst-app Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kuznetsss commented Aug 4, 2026 •

edited

Loading

TimothyBanks Aug 5, 2026 •

edited

Loading