HookScript

HookScript is a Typescript-like language for compiling XRPL Hooks to WebAssembly.

XRPL Hooks Introduction  ·  Documentation  ·  Examples

Features

• Hook API support 🚧.
• Hook logic can be written at the top level, or in a special hook function ^[1].
• Hooks can define their own functions, which are automatically inlined ^[2].
• Linear memory allocation using AssemblyScript stub runtime. No garbage collection ^[3].
• Strings are UTF-8, compatible with Hook API conventions ^[4].
• Core Hook Api functions are automatically imported and wrapped in a higher-level API ^[5].
• High-level classes and functions for working with XRPL accounts, amounts, etc ^[6].

Refer to the Doc for more details.

🚧 Work in progress, not finished yet.

Development instructions

A development environment can be set up by cloning the repository:

git clone https://github.com/eqlabs/assemblyscript.git
cd assemblyscript

After building the compiler, you can invoke it using cli from bin/asc or directly using the compiled bundles from dist folder in any browser/server environments.

Build using Docker.

A docker image can be created using.

docker build -t asc/img .

To create a container and copy built artifacts to the dist folder.

docker create --name asc-cont asc-img && docker cp asc-cont:/app/dist/ ./

Build manually.

Install NodeJS version >=16 and npm >=6.

Install dependencies.

npm install

Build the compiler.

npm run build

Watch for changes.

npm run watch

The full process is documented as part of the repository:

• Compiler instructions
• Runtime instructions
• Test instructions

HookScript Quickstart

This repo contains examples of XRPL Hooks written in HookScript, plus scripts needed to compile, deploy and test them.

Compiler

The HookScript compiler is now installed from NPM and Hook Cleaner functionality has been integrated into it, so that a separate executable is no longer necessary.

Get testnet XRP

The Faucet is on the main page. Make a note of your secret (family seed) because you will need it for all the examples.

Testnet explorer

Use the Testnet Explorer to view transactions, accounts and hook state objects as you go.

File types

1. The example hooks are written in HookScript, using the .ts extension (like AssemblyScript).
2. Hooks compile to .wasm files. These are hook binaries ready to be installed onto an account on the ledger using the SetHook transaction.
3. Javascript files .js are runnable with nodejs and provide a way to install hooks and otherwise interact with the ledger.

Building

To build an example you can run

npm install
npm run compile

from any subdirectory of hook-api-examples. The example package.json in each directory specifies how to build a hook.

Example hooks are generally installed by running node deploy.js. The usage information will be provided at the commandline.

You can check a reported SetHook transaction ID with the Hooks Testnet Explorer.

Finally run the additional .js files to interact with the Hook or write your own interaction.

Viewing state

You can view the current Hook State for your Hook by locating the account it is installed on with the Hooks Testnet Explorer.

You can also run ./rippled account_objects <account on which the hook is installed on> to inspect the Hook's State Data.

Minimum example hook

Please have a look at the accept hook in ./starter/