prepare Hook API

hook/extern.h

@@ -329,5 +329,12 @@ meta_slot(uint32_t slot_no);
 extern int64_t
 xpop_slot(uint32_t slot_no_tx, uint32_t slot_no_meta);
 
+extern int64_t
+prepare(
+    uint32_t write_ptr,
+    uint32_t write_len,
+    uint32_t read_ptr,
+    uint32_t read_len);
+
 #define HOOK_EXTERN
 #endif  // HOOK_EXTERN

src/ripple/app/hook/Enum.h

@@ -14,6 +14,7 @@
 // Override uint256, Feature and Rules for guard checker build
 #define uint256 std::string
 #define featureHooksUpdate1 "1"
+#define featureHooksUpdate2 "1"
 #define fix20250131 "1"
 namespace hook_api {
 struct Rules

src/ripple/app/hook/HookAPI.h

@@ -58,6 +58,9 @@ class HookAPI
     // sto_erase(): same as sto_emplace with field_object = nullopt
 
     /// etxn APIs
+    Expected<Bytes, HookReturnCode>
+    prepare(Slice const& txBlob) const;
+
     Expected<std::shared_ptr<Transaction>, HookReturnCode>
     emit(Slice const& txBlob) const;
 

src/ripple/app/hook/hook_api.macro

@@ -367,3 +367,8 @@ HOOK_API_DEFINITION(
 HOOK_API_DEFINITION(
   int64_t, xpop_slot, (uint32_t, uint32_t),
   featureHooksUpdate1)
+
+// int64_t prepare(uint32_t write_ptr, uint32_t write_len, uint32_t read_ptr, uint32_t read_len);
+HOOK_API_DEFINITION(
+  int64_t, prepare, (uint32_t, uint32_t, uint32_t, uint32_t),
+  featureHooksUpdate2)

src/ripple/app/hook/impl/HookAPI.cpp

@@ -4,6 +4,7 @@
 #include <ripple/app/ledger/OpenLedger.h>
 #include <ripple/app/ledger/TransactionMaster.h>
 #include <ripple/app/tx/impl/Import.h>
+#include <ripple/protocol/STParsedJSON.h>
 #include <cfenv>
 
 namespace hook {
@@ -625,6 +626,122 @@ HookAPI::sto_emplace(
 // sto_erase
 
 /// etxn APIs
+Expected<Bytes, HookReturnCode>
+HookAPI::prepare(Slice const& txBlob) const
+{
+    auto& applyCtx = hookCtx.applyCtx;
+    auto j = applyCtx.app.journal("View");
+
+    if (hookCtx.expected_etxn_count < 0)
+        return Unexpected(PREREQUISITE_NOT_MET);
+
+    Json::Value json;
+
+    // std::shared_ptr<STObject const> stpTrans;
+    try
+    {
+        SerialIter sitTrans{txBlob};
+        json =
+            STObject(std::ref(sitTrans), sfGeneric).getJson(JsonOptions::none);
+    }
+    catch (std::exception& e)
+    {
+        JLOG(j.trace()) << "HookInfo[" << HC_ACC() << "]: prepare Failed "
+                        << e.what() << "\n";
+        return Unexpected(INVALID_ARGUMENT);
+    }
+
+    // add a dummy fee
+    json[jss::Fee] = "0";
+
+    // force key to empty
+    json[jss::SigningPubKey] =
+        "000000000000000000000000000000000000000000000000000000000000000000";
+
+    // force sequence to 0
+    json[jss::Sequence] = Json::Value(0u);
+
+    std::string raddr = encodeBase58Token(
+        TokenType::AccountID, hookCtx.result.account.data(), 20);
+
+    json[jss::Account] = raddr;
+
+    uint32_t seq = applyCtx.view().info().seq;
+    if (!json.isMember(jss::FirstLedgerSequence))
+        json[jss::FirstLedgerSequence] = Json::Value(seq + 1);
+
+    if (!json.isMember(jss::LastLedgerSequence))
+        json[jss::LastLedgerSequence] = Json::Value(seq + 5);
+
+    uint8_t details[512];
+    if (!json.isMember(jss::EmitDetails))
+    {
+        auto ret = etxn_details(details);
+        if (!ret || ret.value() < 2)
+            return Unexpected(INTERNAL_ERROR);
+
+        // truncate the head and tail (emit details object markers)
+        Slice s(
+            reinterpret_cast<void const*>(details + 1),
+            (size_t)(ret.value() - 2));
+
+        // std::cout << "emitdets: " << strHex(s) << "\n";
+        try
+        {
+            SerialIter sit{s};
+            STObject st{sit, sfEmitDetails};
+            json[jss::EmitDetails] = st.getJson(JsonOptions::none);
+        }
+        catch (std::exception const& ex)
+        {
+            JLOG(j.warn()) << "HookInfo[" << HC_ACC() << "]: Exception in "
+                           << __func__ << ": " << ex.what();
+            return Unexpected(INTERNAL_ERROR);
+        }
+    }
+
+    // {
+    //     const std::string flat = Json::FastWriter().write(json);
+    //     std::cout << "intermediate: `" << flat << "`\n";
+    // }
+
+    Blob tx_blob;
+    {
+        STParsedJSONObject parsed(std::string(jss::tx_json), json);
+        if (!parsed.object.has_value())
+            return Unexpected(INVALID_ARGUMENT);
+
+        STObject& obj = *(parsed.object);
+
+        // serialize it
+        Serializer s;
+        obj.add(s);
+        tx_blob = s.getData();
+    }
+
+    // run it through the fee estimate, this doubles as a txn sanity check
+    auto fee = etxn_fee_base(Slice(tx_blob.data(), tx_blob.size()));
+    if (!fee)
+        return Unexpected(INVALID_ARGUMENT);
+
+    json[jss::Fee] = to_string(fee.value());
+
+    {
+        STParsedJSONObject parsed(std::string(jss::tx_json), json);
+        if (!parsed.object.has_value())
+            return Unexpected(INVALID_ARGUMENT);
+
+        STObject& obj = *(parsed.object);
+
+        // serialize it
+        Serializer s;
+        obj.add(s);
+        tx_blob = s.getData();
+    }
+
+    return tx_blob;
+}
+
 Expected<std::shared_ptr<Transaction>, HookReturnCode>
 HookAPI::emit(Slice const& txBlob) const
 {

src/ripple/app/hook/impl/applyHook.cpp

@@ -2575,6 +2575,43 @@ DEFINE_HOOK_FUNCTION(
     HOOK_TEARDOWN();
 }
 
+DEFINE_HOOK_FUNCTION(
+    int64_t,
+    prepare,
+    uint32_t write_ptr,
+    uint32_t write_len,
+    uint32_t read_ptr,
+    uint32_t read_len)
+{
+    HOOK_SETUP();  // populates memory_ctx, memory, memory_length, applyCtx,
+                   // hookCtx on current stack
+
+    if (NOT_IN_BOUNDS(read_ptr, read_len, memory_length))
+        return OUT_OF_BOUNDS;
+
+    if (NOT_IN_BOUNDS(write_ptr, write_len, memory_length))
+        return OUT_OF_BOUNDS;
+
+    ripple::Slice txBlob{
+        reinterpret_cast<const void*>(memory + read_ptr), read_len};
+
+    auto const res = api.prepare(txBlob);
+    if (!res)
+        return res.error();
+
+    auto tx_blob = res.value();
+
+    WRITE_WASM_MEMORY_AND_RETURN(
+        write_ptr,
+        tx_blob.size(),
+        tx_blob.data(),
+        tx_blob.size(),
+        memory,
+        memory_length);
+
+    HOOK_TEARDOWN();
+}
+
 /* Emit a transaction from this hook. Transaction must be in STObject form,
  * fully formed and valid. XRPLD does not modify transactions it only checks
  * them for validity. */

src/ripple/protocol/Feature.h

@@ -74,7 +74,7 @@ namespace detail {
 // Feature.cpp. Because it's only used to reserve storage, and determine how
 // large to make the FeatureBitset, it MAY be larger. It MUST NOT be less than
 // the actual number of amendments. A LogicError on startup will verify this.
-static constexpr std::size_t numFeatures = 90;
+static constexpr std::size_t numFeatures = 91;
 
 /** Amendments that this server supports and the default voting behavior.
    Whether they are enabled depends on the Rules defined in the validated
@@ -378,6 +378,7 @@ extern uint256 const fixInvalidTxFlags;
 extern uint256 const featureExtendedHookState;
 extern uint256 const fixCronStacking;
 extern uint256 const fixHookAPI20251128;
+extern uint256 const featureHooksUpdate2;
 }  // namespace ripple
 
 #endif

src/ripple/protocol/impl/Feature.cpp

@@ -484,6 +484,7 @@ REGISTER_FIX    (fixInvalidTxFlags,             Supported::yes, VoteBehavior::De
 REGISTER_FEATURE(ExtendedHookState,             Supported::yes, VoteBehavior::DefaultNo);
 REGISTER_FIX    (fixCronStacking,               Supported::yes, VoteBehavior::DefaultYes);
 REGISTER_FIX    (fixHookAPI20251128,            Supported::yes, VoteBehavior::DefaultYes);
+REGISTER_FEATURE(HooksUpdate2,                  Supported::yes, VoteBehavior::DefaultNo);
 
 // The following amendments are obsolete, but must remain supported
 // because they could potentially get enabled.

src/ripple/protocol/jss.h

@@ -101,6 +101,7 @@ JSS(Invalid);                  //
 JSS(Invoke);                   // transaction type
 JSS(InvoiceID);                // field
 JSS(LastLedgerSequence);       // in: TransactionSign; field
+JSS(FirstLedgerSequence);      // in: TransactionSign; field
 JSS(LedgerHashes);             // ledger type.
 JSS(LimitAmount);              // field.
 JSS(NetworkID);                // field.
@@ -140,6 +141,7 @@ JSS(HookState);                // ledger type.
 JSS(HookStateData);            // field.
 JSS(HookStateKey);             // field.
 JSS(EmittedTxn);               // ledger type.
+JSS(EmitDetails);              // field.
 JSS(SignerList);               // ledger type.
 JSS(SignerListSet);            // transaction type.
 JSS(SigningPubKey);            // field.

src/test/app/HookAPI_test.cpp

@@ -18,7 +18,9 @@
 //==============================================================================
 #include <ripple/app/hook/HookAPI.h>
 #include <ripple/basics/StringUtilities.h>
+#include <ripple/beast/unit_test/suite.hpp>
 #include <ripple/json/json_writer.h>
+#include <ripple/protocol/SField.h>
 #include <ripple/protocol/STAccount.h>
 #include <limits>
 #include <test/app/Import_json.h>
@@ -75,6 +77,84 @@ class HookAPI_test : public beast::unit_test::suite
         BEAST_EXPECT(true);
     }
 
+    void
+    test_prepare(FeatureBitset features)
+    {
+        testcase("Test prepare");
+        using namespace jtx;
+
+        auto const alice = Account{"alice"};
+        auto const bob = Account{"bob"};
+
+        using namespace hook_api;
+        Env env{*this, features};
+
+        STTx invokeTx = STTx(ttINVOKE, [&](STObject& obj) {});
+        OpenView ov{*env.current()};
+        ApplyContext applyCtx = createApplyContext(env, ov, invokeTx);
+
+        STTx const emitInvokeTx = STTx(ttINVOKE, [&](STObject& obj) {});
+
+        {
+            // PREREQUISITE_NOT_MET
+            auto hookCtx =
+                makeStubHookContext(applyCtx, alice.id(), alice.id(), {});
+            auto& api = hookCtx.api();
+            auto tx = emitInvokeTx;
+            Serializer s = tx.getSerializer();
+            s.add8(0);  // invalid value
+            auto const result = api.prepare(s.slice());
+            BEAST_EXPECT(result.error() == PREREQUISITE_NOT_MET);
+        }
+
+        {
+            // Invalid txn
+            auto hookCtx = makeStubHookContext(
+                applyCtx,
+                alice.id(),
+                alice.id(),
+                {
+                    .expected_etxn_count = 1,
+                });
+            auto& api = hookCtx.api();
+            auto tx = emitInvokeTx;
+            Serializer s = tx.getSerializer();
+            s.add8(0);  // invalid value
+            auto const result = api.prepare(s.slice());
+            BEAST_EXPECT(result.error() == INVALID_ARGUMENT);
+        }
+
+        {
+            // success
+            auto hookCtx = makeStubHookContext(
+                applyCtx,
+                alice.id(),
+                alice.id(),
+                {
+                    .expected_etxn_count = 1,
+                });
+            auto& api = hookCtx.api();
+            auto tx = emitInvokeTx;
+            Serializer s = tx.getSerializer();
+            auto const result = api.prepare(s.slice());
+            BEAST_EXPECT(result.has_value());
+
+            SerialIter sit(Slice(result.value().data(), result.value().size()));
+            STObject st(sit, sfGeneric);
+            BEAST_EXPECT(st.getFieldAmount(sfFee) > XRPAmount(0));
+            BEAST_EXPECT(st.getFieldU32(sfSequence) == 0);
+            BEAST_EXPECT(st.getAccountID(sfAccount) == alice.id());
+            auto const seq = applyCtx.view().info().seq;
+            BEAST_EXPECT(st.getFieldU32(sfFirstLedgerSequence) == seq + 1);
+            BEAST_EXPECT(st.getFieldU32(sfLastLedgerSequence) == seq + 5);
+            BEAST_EXPECT(st.isFieldPresent(sfEmitDetails));
+
+            auto const result2 =
+                api.emit(Slice(result.value().data(), result.value().size()));
+            BEAST_EXPECT(result2.has_value());
+        }
+    }
+
     void
     test_emit(FeatureBitset features)
     {
@@ -4441,6 +4521,7 @@ class HookAPI_test : public beast::unit_test::suite
         test_rollback(features);
         testGuards(features);
 
+        test_prepare(features);
         test_emit(features);
         test_etxn_burden(features);
         test_etxn_generation(features);