Hooks Amendment

[RichardAH]

The Hooks Amendment adds smart contract-like functionality to the XRP Ledger. With this amendment users may choose to install small, efficient web assembly binaries onto their XRPL Accounts using the new SetHook transactor. These binaries allow for custom logic about which transactions are accepted (or rejected) and can also emit new transactions and manage custom information called Hook State.

These early blogs describe the premise of Hooks:

• Hooked #0: Intro
• Hooked #1: Smart Contracts on the XRP Ledger
• More ...

---

Getting Started

Hooks Builder

A developer-centric Hooks IDE for your browser, connected to the testnet. (No download is required.)

Hooks Transaction Explorer

A custom technical explorer for the testnet.

Hooks V2 Staging Testnet

Consists of 9 nodes, peering information: https://xumm.notion.site/Hooks-V2-staging-net-info-XLS20-518fa261c5cd49d2bcb89a5b9e7bef05.

Hooks Documentation

Is not present on github, lives exclusively on redme.io.

Test Plan

1. The codebase for Hooks is being tested live on the community-run Hooks V2 Staging Testnet.
2. Javascript test cases are being actively developed here: https://github.com/XRPL-Labs/xrpld-hooks/tree/develop/hook
3. Unit tests are planned but have not yet been started.

Notes

1. This PR is a transfer of the current Hooks codebase to XRPLF/rippled onto its own branch.
2. It is not production ready and should not be used in production.
3. This PR is squashed from XRPL-Labs/xrpld-hooks.

Future Tasks

• Port javascript tests to unit tests.
• Improved APIs for accessing Hook state, namespace and other ledger objects.
• Clear backlog of existing issues on https://github.com/XRPL-Labs/xrpld-hooks/issues.
• Fix WASMEDGE in build system to allow for static builds (currently only non-static builds work).
• Small refactors and some small rewrites needed in wasm binary parsing in SetHook transactor.
• Find and clean up all TODOs in code.
• Security review.

[RichardAH]

Thanks for the review, Nik. I will get on to these suggestions when back at work

[nbougalis]

Thanks for the review, Nik. I will get on to these suggestions when back at work

Thank me after I'm done reviewing. This was just the opening salvo. Enjoy your vacation :smiley:

[greg7mdp]

@RichardAH - I think the issue might be that you used curly braces for the std::string constructor. Can you try using parentheses?

std::string raddr((char*)(memory + read_ptr), read_len);

greg

[RichardAH]

@RichardAH - I think the issue might be that you used curly braces for the std::string constructor. Can you try using parentheses? std::string raddr((char*)(memory + read_ptr), read_len); greg

    std::string raddr((char*)(memory + read_ptr), read_len);

    auto const result = decodeBase58Token(raddr, TokenType::AccountID);
    if (result.empty())
        return INVALID_ARGUMENT;


    WRITE_WASM_MEMORY_AND_RETURN(
        write_ptr, write_len,
        result.data(), 20,
        memory, memory_length);

Still doesn't work for me. Can you please test yourself also? It's technically possible my specific build environment is responsible for the outcome I see

[greg7mdp]

Still doesn't work for me. Can you please test yourself also? It's technically possible my specific build environment is responsible for the outcome I see

Hum, I apologize, I'm new at Ripple and I don't know how I would test this. I don't see a JTX test for this.

I tried building your branch on windows, but there are errors:

13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(209,9): error C2143: syntax error: missing '}' before 'constant' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_7_cxx.cxx)
13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(209,9): error C2059: syntax error: 'constant' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_7_cxx.cxx)
13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(222,5): error C2143: syntax error: missing ';' before '}' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_7_cxx.cxx)
13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(323,1): error C2059: syntax error: '}' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_7_cxx.cxx)
13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(323,1): error C2143: syntax error: missing ';' before '}' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_7_cxx.cxx)
13>C:\greg\github\ripple\rippled\src\ripple/app/hook/Enum.h(209,9): error C2143: syntax error: missing '}' before 'constant' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_6_cxx.cxx)
...

The first one is because the enum OVERFLOW in app/hook/Enum.h:

        OVERFLOW = -30,                 // if an operation with a float results in an overflow

clashes with the windows macro defined in corectr_math.h:

#if defined(_CRT_INTERNAL_NONSTDC_NAMES) && _CRT_INTERNAL_NONSTDC_NAMES

    #define DOMAIN      _DOMAIN
    #define SING        _SING
    #define OVERFLOW    _OVERFLOW
    #define UNDERFLOW   _UNDERFLOW

[RichardAH]

The first one is because the enum OVERFLOW in app/hook/Enum.h:

        OVERFLOW = -30,                 // if an operation with a float results in an overflow

clashes with the windows macro defined in corectr_math.h:

I've actually seen this conflict before (can't recall when). It doesn't occur on the compilers I use but I will change the name for you now.

[greg7mdp]

I've actually seen this conflict before (can't recall when). It doesn't occur on the compilers I use but I will change the name for you now.

Thanks @RichardAH, this addressed the first issue. It also doesn't build with stdc++17, so I switched to stdc++20. Now I have a boost issue:

13>C:\soft\boost_1_71_0\boost/outcome.hpp(32,20): error C2230: could not find module 'outcome_v2_0' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_17_cxx.cxx)

The doc still states that boost 1.70 is required, and I'm using 1.71.

[RichardAH]

I've actually seen this conflict before (can't recall when). It doesn't occur on the compilers I use but I will change the name for you now.

Thanks @RichardAH, this addressed the first issue. It also doesn't build with stdc++17, so I switched to stdc++20. Now I have a boost issue:

13>C:\soft\boost_1_71_0\boost/outcome.hpp(32,20): error C2230: could not find module 'outcome_v2_0' (compiling source file C:\greg\github\ripple\rippled\build_win\CMakeFiles\rippled.dir\Unity\unity_17_cxx.cxx)

The doc still states that boost 1.70 is required, and I'm using 1.71.

I only build on linux, so I'm not sure 😬 Is this specific to the Hooks PR or does rippled in general cause this?

[greg7mdp]

I only build on linux, so I'm not sure 😬 Is this specific to the Hooks PR or does rippled in general cause this?

The current version of rippled from XRPL (1.9.2) builds fine with stdc++17 and boost 1.71. Not sure where these new requirements originate from. I'm trying to build the Hooks PR with C++20 and boost 1.75, and I still have errors. It looks like it tries to import boost outcome as a C++ module. I'm not quite sure how to turn this off when C++20 is set.

#if defined(__cpp_modules) && !defined(GENERATING_OUTCOME_MODULE_INTERFACE)
import outcome_v2_0;
#else
...

[scottschurr]

Just to stick my nose in briefly, I'd like to discourage us from using modules in C++20. There are a number of issues that still need to be worked out, particularly with cross-platform applications. There are folks actively working on resolving these problems in C++23.

[RichardAH]

The current version of rippled from XRPL (1.9.2) builds fine with stdc++17 and boost 1.71. Not sure where these new requirements originate from. I'm trying to build the Hooks PR with C++20 and boost 1.75, and I still have errors. It looks like it tries to import boost outcome as a C++ module. I'm not quite sure how to turn this off when C++20 is set.

I've never tried building Hooks on Windows. I will try now and see if I can shed some light on this. Edit: Windows builds are a maze. I'm going to let someone else who is an expert in them figure this out 😛

[ximinez]

I've never tried building Hooks on Windows. I will try now and see if I can shed some light on this. Edit: Windows builds are a maze. I'm going to let someone else who is an expert in them figure this out 😛

@greg7mdp @RichardAH I haven't been keeping up with this conversation, but I happened to notice this comment, and tried to build for the first time on my Windows box. It failed to even get to rippled code, choking on the wasmedge dependency. Long story short, it looks like it has a dependency on LLVM, which isn't as commonly available on Windows by default. Here's the troublesome command and output: https://gist.github.com/ximinez/bb214950c64defe0404c44d02c3f7dc8

One option is to just document the dependency. Optimally, it would be great if rippled's CMake config could treat LLVM as yet another external project.

[intelliot]

@RichardAH what's your preferred path forward for this PR?

[RichardAH]

We are launching hooks on a sidechain so this can close

[RichardAH]

By popular demand Hooks PR is being reopened https://x.com/sentosumosaba/status/1756877266481729958

Next steps:

1. Accept the PR to place Hooks on its own branch
2. New PR/s to bring the branch up to date with rippled.
3. New PR/s to bring the branch up to date with production Hooks as runs on Xahau.
4. New PR/s to harmonise Hooks with mainnet (for example it needs testing with xls 20 and other amendments).

We will provide developer time on points 3 and 4. We expect Ripple to provide dev time on 2 and 4.

Let’s go!

[intelliot]

Suggested commit message:

Introduce in-development Hooks amendment (#4225)

* Hooks V2 squashed from
  https://github.com/XRPL-Labs/xrpld-hooks/tree/006524a10aa406d09742dae69a9cf271bdea0d26

* Include changes from code review

Introduce "Hooks" functionality with the new SetHook transactor. This
significantly expands the scope of transaction processing capabilities
with an implementation that supports the execution of programmable
scripts that attach to accounts and execute during transactions. This
provides programmability and allows for advanced use cases involving
transaction validation, automation, and complex multi-signature
arrangements. The core transaction pipeline executes hooks, manages
their states, and handles associated fees. Adjustments across the code
enable seamless integration of hooks with existing functionality, e.g.
signer lists. This is a large advancement in the architecture and
functionality of the system.

Additional testing, including performance testing, and reviews,
including security reviews, are necessary before this change should be
considered production-ready. Additionally, there is a need to modify the
change so that it can build on Windows, which is currently a supported
platform for development purposes.