Hooked #3: Tech Preview Release (Play with Smart Contracts on the XRP ledger!)
Tags: xrpl, xrp, xrplhooks, amendment
Published: 2020-11-18 19:41:58

> ##### Please note
> Since this blog was published [a lot has happened](https://twitter.com/XRPLLabs/status/1545354585430171648). The Hooks Amendment is now running on a [public testnet](https://xumm.notion.site/Hooks-V2-staging-net-info-XLS20-518fa261c5cd49d2bcb89a5b9e7bef05) and has a [public "Builder" where you (devs) can code Hooks and deploy them to the testnet](http://hooks.xrpl.org/), 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](https://dev.to/wietse/hooked-1-smart-contracts-on-the-xrp-ledger-5eb6)
- [Hooked #2: Hooks & Security (Smart Contracts on the XRP ledger)](https://dev.to/wietse/hooked-2-hooks-security-smart-contracts-on-the-xrp-ledger-83e)

# 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](https://github.com/RichardAH), hats off to him!), testing, etc. [we (the people at XRPL Labs)](http://xrpl-labs.com) 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:

{% gist https://gist.github.com/WietseWind/14babf8b12a39546ca31ddddeec70ef9 file=run.sh %}

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:

{% gist https://gist.github.com/WietseWind/14babf8b12a39546ca31ddddeec70ef9 file=logs.sh %}

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](https://github.com/RichardAH/rippled-hooks/tree/hooks/hook-api-examples) from the Github repository.

# Let's play with hooks

This is where you read the **Hooks Tech Preview [README.md](https://github.com/RichardAH/rippled-hooks/blob/hooks/hook-api-examples/README.md)**. This README.md exists inside the Docker container, and can be found [in the Github repository](https://github.com/RichardAH/rippled-hooks/blob/hooks/hook-api-examples). 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:

{% github RichardAH/rippled-hooks %}

# 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:

{% gist https://gist.github.com/WietseWind/14babf8b12a39546ca31ddddeec70ef9 file=returnvalues.c %}

## 4. Hook API Function List

The best way to view the API function list is by reading the header comments: [hookapi.h](https://github.com/RichardAH/rippled-hooks/blob/hooks/hook-api-examples/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](https://dev.to/search?q=hooked%20xrpl&filters=class_name:Article), the [source & README's](https://github.com/XRPL-Labs/xrpld-hooks/tree/development/hook-api-examples) and ... just a **little** more patience as we're on track for a Q1 public testnet release :)

## Discussion

Discussions: [here »](https://github.com/XRPL-Labs/xrpld-hooks/discussions)