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)
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.
🐉 🐲 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.
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.
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.
The work-in-progress repository for Hooks has been opened to the public:
Hooks Technology Preview
This is a fork of the rippled codebase incorporating the work-in-progress "Hooks" amendment. This amendment will allow web assembly smart contracts to run directly on the XRP ledger when completed and adopted.
Building rippled can be non-trivial, especially in this case since modified libraries are used. We have provided a tech-preview docker container for your convenience. Follow the steps below to use it.
Starting the container
- Download and install docker.
- To download the container use:
docker pull richardah/xrpld-hooks-tech-preview
- Then to run the container interactively use:
docker run --name xrpld-hooks richardah/xrpld-hooks-tech-preview & docker exec -it xrpld-hooks /bin/bash
- Set up a second terminal to view the log:
Open a new terminal window on your system and run.
docker exec -it xrpld-hooks tail -f log
This will show you the trace log of xrpld as it runs, which will be important for knowing if your transactions fail or…
The Hook API establishes several conventions to reduce friction for hook developers:
Hooks are named in the following way:
noun [ _ ( adjective | noun#2 ) ][ _verb ]
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'
state_set() means 'set state'
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.
Hooks can only pass integer values back to
xrpld. However this includes pointers within its own memory.
- Pointers are named according to what
xrpldis expected to do with the pointer. For example if
xrpldis expected to write to the pointer it will be named
- 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.
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:
If there are writing pointers they always come at the start of the parameter list.
If there are non-pointer parameters they always come at the end of the parameter list.
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:
The best way to view the API function list is by reading the header comments: hookapi.h
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.
Discussions: here »