Please note

Since this blog was published a lot has happened. The Hooks Amendment is now running on a public testnet and has a public "Builder" where you (devs) can code Hooks and deploy them to the testnet, straight from your browser.

If you haven't already read the previous two blogs please do so first:

• Hooked #1: Smart Contracts on the XRP ledger
• Hooked #2: Hooks & Security (Smart Contracts on the XRP ledger)

Hooked #3: Tech Preview Release

This is another technical blog about the upcoming Hooks Amendment for the XRP Ledger. After months of discussing, tinkering, designing, discussing some more, building (99% Richard, hats off to him!), testing, etc. we (the people at XRPL Labs) are really excited to publish this blog, source code, sample hooks & a docker container so you can run your own local Hooks-enabled XRPL.

Get the Tech Preview running with Docker

🐉 🐲 Here be dragons! We want to stress this is a tech preview it is not indicative of the final Hooks Amendment nor has it been optimised. The purpose of the preview is to demonstrate what Hooks will be able to do and how they will work in general.

To run the container interactively use:

If you want to play around, it makes sense to open two terminals, one with the logs generated by rippled (to see the result/logging of what you execute), and one to issue your commands.

To set up a second terminal to view the log: open a new terminal window on your system and run:

This will show you the trace log of xrpld as it runs, which will be important for knowing if your transactions fail or succeed and what actions the hooks take.

Interacting with the Docker

After following the above steps you will be inside a shell inside the container. Rippled will already be running with the correct settings and the Hooks amendment enabled.

When you execute something in the docker container, you'll do so from the path:
/opt/rippled-hooks (inside the container)

This path contains the contents of this folder from the Github repository.

Let's play with hooks

This is where you read the Hooks Tech Preview README.md. This README.md exists inside the Docker container, and can be found in the Github repository. This Readme contains instructions on building, installing and interacting with the example hooks. Every hook folder contains a hook written in C that can be built to a WebAssembly Hook, to be installed with a node (javascript) file inside the folder.

The sample hooks included are:

• accept - This hook is a minimum example hook.
• carbon - Installing this hook causes the account to send a 1% carbon-offset txn each time another txn is sent from the account.
• firewall - Installing this hook causes transactions from blacklisted accounts to be rejected Installing is a two step process, first create the blacklist storage account and install the blacklist, next install the firewall hook on the protected account.
• liteacc - Installing this hook causes the account to become a multi-party pool account with each user acquiring a unique dest tag with which they can receive funds on the account.

Source Code

The work-in-progress repository for Hooks has been opened to the public:

docker rmi -f xrpllabsofficial/xrpld-hooks-testnet

docker run -d --name xrpld-hooks xrpllabsofficial/xrpld-hooks-testnet
docker exec -it xrpld-hooks bash

Hook API

The Hook API establishes several conventions to reduce friction for hook developers:

1. Naming Convention

Hooks are named in the following way:

noun [ _ ( adjective | noun#2 ) ][ _verb ]

adjective, noun#2 and verb are optional. If not specified the verb is implicitly get. This may look confusing at first but it is intuitive after some examples:

state() means 'get state'

And

state_set() means 'set state'

And

state_foreign() means "get foreign state" e.g. the state of a hook from another account.

Where possible the leading noun indicates the subject of the API, e.g. state but to avoid turning the API into spaghetti the leading noun can also be a group of only loosely related APIs e.g. util.

2. Parameter Convention

Hooks can only pass integer values back to xrpld. However this includes pointers within its own memory.

1. Pointers are named according to what xrpld is expected to do with the pointer. For example if xrpld is expected to write to the pointer it will be named write_ptr.
2. Pointers are always followed by a byte length indicating the size of the buffer to read or write to/from. This parameter is named in the same convention as above e.g. write_len.

3. If there are multiple pointers of the same type a leading character indicating the name is used to disambiguate them. E.g. a key and data set of pointer-length pairs would look like this:

   kread_ptr, kread_len, dread_ptr, dread_len

4. If there are writing pointers they always come at the start of the parameter list.

5. If there are non-pointer parameters they always come at the end of the parameter list.

3. Return Values

All Hook APIs return int64_t. If the return value is non-negative it is a success. Typically a positive integer reflects the number of bytes read or written (depending on the API) or the amount of actions taken. However in some cases (e.g util_subfield) the return value of the API is encoded into a positive int64_t.

If the return value is negative it is always one of the well-defined error codes. At time of writing these are:

4. Hook API Function List

The best way to view the API function list is by reading the header comments: hookapi.h

Next Blog

We will be releasing further blogs discussing design choices and development progress over the coming weeks and months in the lead-up to a live Hooks Testnet.

Please check the other blogs, the source & README's and ... just a little more patience as we're on track for a Q1 public testnet release :)

Discussion

Discussions: here »