hooks-rs

Xahau hooks in Rust and CLI to build and deploy hooks.

Demo

Quickstart

Warning

Only MacOS and Linux are supported for now. If you are on Windows, please use Docker (see below).

Before anything, install deno.

deno install --allow-all --allow-scripts --global jsr:@hooks-rs/cli --name hooks # install the CLI as "hooks"

hooks # see help

hooks up # install binary dependencies

hooks new hooks-example # init new project called "hooks-example"

cd hooks-example

hooks account # create a new account for deployment

hooks build # build hook

hooks deploy --hook-on INVOKE # deploy the hook

Available CLI options

new        <projectName>  - Initializes a new hooks-rs template in a new folder in the current working
                            directory
up                        - Installs all prerequisite binaries
check                     - Checks if all prerequisite binaries are installed and available in PATH
account                   - Create a new testnet account stored in account.json
build                     - Compile and preprocess a hook
deploy                    - Build and deploy a hook to Xahau network
uninstall                 - Uninstall all prerequisite binaries installed by 'up' command.
test                      - Run tests for the project

Examples

This is the most basic accept.rs hook, and it looks like this:

#![no_std]
#![no_main]

use hooks_rs::*;

#[no_mangle]
pub extern "C" fn cbak(_: u32) -> i64 {
    0
}

#[no_mangle]
pub extern "C" fn hook(_: u32) -> i64 {
    // Every hook needs to import guard function
    // and use it at least once
    max_iter(1);

    // Log it to the debug stream, which can be inspected on the website or via wss connection
    let _ = trace(b"accept.rs: Called.", b"", DataRepr::AsUTF8);

    // Accept all
    accept(b"accept.rs: Finished.", line!().into());
}

Other examples are under /examples directory. Check them out!.

Documentation

Most implementations are thoroughly documented. Please check out the book and crate docs.

• The book
• Crate docs
• Xahau docs

Running with Docker

Sometimes, it might be tricky to install the CLI right on your machine and run it because it installs several binaries in your system, which might sometimes go weird. In such a case, use 9oel/hooks-cli:latest to run the CLI without having to affect your local machine, like this:

docker run \
  --init \
  -p 1993:1993 \
  -v $PWD:/app \
  9oel/hooks-cli:latest hooks new my-project

cd my-project

docker run \
  --init \
  -p 1993:1993 \
  -v $PWD:/app \
  9oel/hooks-cli:latest hooks build

Tested functions

Most APIs are supported but yet to be tested. Contributions are welcome. The list below shows which features are tested and which ones are not.

Click to expand

Control

• accept
• rollback

Emitted transaction

• etxn_burden
• etxn_details
• etxn_fee_base
• etxn_nonce
• etxn_reserve
• etxn_generation
• emit

Float

• float_set
• float_multiply
• float_mulratio
• float_negate
• float_compare
• float_sum
• float_sto
• float_sto_set
• float_invert
• float_divide
• float_one
• float_exponent
• float_mantissa
• float_sign
• float_int
• float_root
• float_log

Ledger

• fee_base
• ledger_seq
• ledger_last_hash
• ledger_last_time
• ledger_nonce
• ledger_keylet

State

• state
• state_set
• state_foreign
• state_foreign_set

Trace

• trace
• trace_num
• trace_float

Originating transaction

• otxn_burden
• otxn_field
• otxn_generation
• otxn_id
• otxn_type
• otxn_slot
• otxn_param
• meta_slot

Utilities

• util_raddr
• util_accid
• util_verify
• util_sha512h
• util_keylet

Hook context

• hook_account
• hook_hash
• hook_param
• hook_param_set
• hook_skip
• hook_pos
• hook_again

Serialization

• sto_subfield
• sto_subarray
• sto_emplace
• sto_erase
• sto_validate

Slot

• slot
• slot_clear
• slot_count
• slot_set
• slot_size
• slot_subarray
• slot_subfield
• slot_type
• xpop_slot
• slot_float

C bindings

The latest header files can be found at https://github.com/XRPLF/hook-macros

Credits

• This is a fork of otov4its/xrpl-hooks which has been unmaintained for a long time.
• Lots of examples and codes have been adopted from dangell7's repositories.

Contributing

There are still many parts of the C API that are not supported yet. The first priority for now would be to get all of them working.

If you have all checkboxes below ticked, you can proceed to create a PR:

• You have implemented something that wasn't here before
• You have created an integration test to prove that it works. See /tests folder to see the existing integration test examples. Currently, each integration test would cover the smallest unit of testable 'chunk', because hooks is impossible to be tested without a live connection with an actual XRPL node, no matter if it is on local docker or is one of the testnet nodes. Therefore, an integration test is somewhat like an unit test but still connects to an actual XRPL node to run the hook to see if it actually works. Make sure the all of the state changes caused by the hook are correctly asserted, before and after the execution of the hook.
• You have created an example in /examples folder. The example hook file should contain the most minimal example of how the feature that you have added can be used. Use this example as a documentation for the function as well, so that it can appear in the generated documentation.
• CI is passing. Unless all workflows give you a green tick, the PR is unlikely to be reviewed.
• The PR has a sufficient description of what it adds or changes. The title of the PR would usually just follow semantic commit messages convention. Do not worry about the commit messages themselves that much, since they are going to be squashed anyway.

Remember that this repository is a novel combination of two amazing concepts: Rust and Hooks. And neither of these are easy nor familiar with the general audience. If you are not sure where to start, probably start with the book, which will give you some idea to start with.