Skip to content

feat: Generate HostBindings from rippled's host function list - #316

Open
sappenin wants to merge 15 commits into
mainfrom
df/generate-host-bindings
Open

sappenin wants to merge 15 commits into
mainfrom
df/generate-host-bindings

Conversation

@sappenin

@sappenin sappenin commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

This PR generates the HostBindings trait found in host_bindings_trait.rs from the definition in the rippled repo. Because the version found in rippled is not quite suitable for usage by the stdlib, we must generate a version from the authoritative source (as opposed to using that source directly).

This PR also removes the "host audit" scripts and tooling because those are no longer needed (instead of checking for conformance, we generate instead).

Summary

  • tools/generate-host-bindings parses rippled's crates/xrpl-host-functions/src/lib.rs at the commit pinned in XRPLD_DOCKER_IMAGE and generates host_bindings_trait.rs (rippled docs verbatim) + host_bindings_list.rs (for_each_host_function!).
  • The wasm / empty / test implementations are now macro_rules! callbacks over that list and no longer change when a host function is added.
  • scripts/generate-host-bindings.sh --check is the CI drift gate (run-all.sh + new check_host_bindings_generated job); the regex audit (host-function-audit.sh, compareHostFunctions.js) is removed.
  • every_host_function_has_a_default_expectation (macro-expanded from the generated list) fails cargo test if a listed host function has no default mock expectation.

This PR Supersedes #293.

Behaviour

Import names and wire signatures are unchanged (63/63 match today's hand-written set). Only trait parameter names changed (derived from rippled: out_buff_ptr→out_ptr, cache_num→cache_idx, …); all call sites are positional. A module-level #[allow(clippy::too_many_arguments)] on host_bindings_trait in host/mod.rs replaces the old per-method allows.

Follow-ups

  • Migrate generate-sfields.sh / generate-tx-flags.sh / generate-ledger-objects.sh from branch HEAD to the same commit pin.
  • e2e probes for the 10 host functions no contract imports today.

Test plan

  • CI green including check_host_bindings_generated

sappenin and others added 11 commits September 29, 2026 15:33
Scaffold tools/generate-host-bindings (standalone, publish = false) with
the syn-based parser for crates/xrpl-host-functions/src/lib.rs and the
pinned upstream fixture at 21560cdf.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Defaults to the rippled commit pinned in XRPLD_DOCKER_IMAGE.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ne list

host_bindings_trait.rs and the new host_bindings_list.rs are generated by
tools/generate-host-bindings from rippled's host_functions! block at the
commit pinned in XRPLD_DOCKER_IMAGE. The wasm, empty and test
implementations are now macro callbacks over that list. Parameter names
are derived from rippled (out_buff_ptr -> out_ptr, cache_num -> cache_idx,
...); all call sites are positional so behaviour is unchanged. A generated
test fails if a listed host function has no default mock expectation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Replaces the disabled host_function_audit job and
tools/compareHostFunctions.js with generate-host-bindings.sh --check,
wired into run-all.sh. Deletes the superseded generateTestHostBindings.js.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@sappenin
sappenin marked this pull request as draft September 29, 2026 22:25

@ripple-code-reviewer ripple-code-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This diff only touches CI workflow config, workspace docs, and the root Cargo.toml exclude list (the actual generator code and generated files aren't in this diff chunk). The test.yml change correctly swaps the disabled regex-based host_function_audit job for an active check_host_bindings_generated job, and AGENTS.md/Cargo.toml updates are consistent with the stated design. No correctness, security, or infrastructure issues found in the shown hunks; can't verify claims about scripts/tools not included in this diff (e.g., clippy.sh/fmt.sh coverage of the new tooling workspace) so those aren't flagged per prior guidance against asserting on unseen source.

The spec is kept locally in workbench/; the executed plan is dropped (still in history at 7fd255c).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@sappenin sappenin self-assigned this Sep 29, 2026
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@sappenin sappenin changed the title feat: generate HostBindings from rippled's host_functions! block feat: Generate HostBindings from rippled's host function list Sep 29, 2026
@sappenin
sappenin marked this pull request as ready for review September 29, 2026 22:57
… claims

- Rewrite comments in the generator, the three host-binding impls and host/mod.rs
  in plain English; regenerate the trait/list docs from the updated emitter.
- Fix wrong statements: the empty stubs do not implement HostBindings and do not
  panic (they return their last argument); the empty include! is not selected by
  --features test-host-bindings; six e2e comments pointed at a file that no longer
  exists.
- Drop the redundant per-item #[cfg] attributes in host_bindings_test.rs; mod.rs
  already gates the whole file.
- Read XRPLD_DOCKER_IMAGE in generate-host-bindings.sh the same way
  docker-rippled.sh does.
- Delete the stray CLAUDE.md~HEAD merge leftover.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

@ripple-code-reviewer ripple-code-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This diff only touches xrpl-common-stdlib/src/host/mod.rs, and the changes are limited to: (1) rewording/expanding the module-level doc comment to describe the new codegen pipeline, (2) adding #[allow(clippy::too_many_arguments)] to the host_bindings_trait module declaration, and (3) adding an unconditional include!("host_bindings_list.rs") before the three cfg-gated implementation includes, with updated inline cfg comments. The ordering is correct (macro_rules! must be defined before use, and it's placed before the three includes that consume it), the cfg gates are unchanged in logic (just reworded comments), and the lint allow is scoped appropriately to replace the old per-method allows as described in the PR. I don't see any correctness, security, or maintainability issues introduced by this small, mechanical change.

…ppled commit

generate-host-bindings.sh now overwrites the generator's test fixture with a
verbatim copy of the rippled lib.rs it just fetched, and --check diffs the two.
Before this the fixture was a one-time hand copy that nothing refreshed, so it
could silently keep testing an old ABI after the pin moved.

The fixture's module header goes back to rippled's original text, since the
script would overwrite any local edits on the next run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

@ripple-code-reviewer ripple-code-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This diff only touches xrpl-common-stdlib/src/host/mod.rs, updating documentation comments to reflect the new codegen pipeline, replacing per-method clippy allows with a single module-level #[allow(clippy::too_many_arguments)], and inserting an early include!("host_bindings_list.rs") so the for_each_host_function! macro is defined before the three cfg-gated includes that consume it. The change is low-risk: it's comment rewording plus a straightforward reordering of includes with a documented rationale (macro_rules! visibility requires definition-before-use). No logic changes are visible in this diff, and the actual generated files (host_bindings_trait.rs, host_bindings_list.rs) and the generator tool itself are not part of this diff, so their correctness can't be assessed here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants