Testnet FaucetExplorerHooks API Docs

Debugging Hooks

How to print "hello world" from your Hook!

How can I debug a Hook?

The Hook API provides a set of functions in the namespace trace which write output to the xrpld log file when xrpld is configured with the trace log-level. These functions, generally speaking, allow you to see the value of variables, buffers and otherwise trace the execution and state of a Hook at runtime.

📘 Hint

At time of writing there is no interactive Hook Debugger. You must use the trace functions.

Trace APIs

The following trace functions are available in the Hooks API

Hook API
What it does

Print a utf-8 message, followed by a user-specified buffer (this last optionally as hex.)

Print a utf-8 message, followed by an integer.

Print a utf-8 message, followed by an XFL Floating point number.

trace_slot

Print a utf-8 message, followed by the serialized contents of a slot.

Example

The following code will print a single trace line then accept the Originating Transaction.

#include "../hookapi.h"
int64_t hook(int64_t reserved)
{
  trace_num(SBUF("A number"), 10);
  accept(0,0,0);
  return 0;
}

An example of the log-line produced by xahaud when a payment is sent out of or into the Hook Account:

2021-Apr-13 13:59:11.083700726 UTC View:TRC
    HookTrace[rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh-rE3SfnjwfzZFL3JK9cLVfJuy8Ar1XnCqPw]:
        A number 10

The above appears in the log as all-one-line, but split here for visibility.

👍 Use testnet

The Xahau Testnet is the perfect place to test your Hooks.

Log format

A breakdown of the log format appears in the table below

Part
Description
#

2021-Apr-13 13:59:11.083700726 UTC View:TRC

xahaud's prefix to the log line

1

HookTrace

This is a trace initiated by the Hook itself not some other information about the Hook. Other information is available on tags HookError, HookEmit and HookInfo.

2

[rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh

The first account in the square brackets is the Hook Account.

3

-rE3SfnjwfzZFL3JK9cLVfJuy8Ar1XnCqPw]:

The second account in the square brackets is the Originating Account.

4

A number

This is the message the Hook was told to deliver before the trace payload

5

10

This is the trace payload

6

🚧 Tip

Xahaud produces a lot of output. It is therefore generally advisible to grep logs for the account/s you are interested in. For example use: tail -f log | grep HookTrace | grep <account>

Last updated