mirror of
https://github.com/Xahau/xahaud.git
synced 2026-06-03 16:56:36 +00:00
update readme
This commit is contained in:
Richard Holland
134
README.md
134
README.md
@@ -1,136 +1,6 @@
|
||||
# Hooks Public Testnet
|
||||
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.
|
||||
# Hooks Public Testnet + Documentation
|
||||
|
||||
## Docker Container
|
||||
Building `rippled` can be non-trivial, especially in this case since modified libraries are used. We have provided a testnet docker container for your convenience. This container contains an instance of `rippled` configured as a "Hooks stock node" running on the Public Testnet. You can interact with it using the steps below:
|
||||
|
||||
### Updating an existing container
|
||||
If you already have the docker image and need to update then use this instruction to pull and run the new version
|
||||
```bash
|
||||
docker rmi -f xrpllabsofficial/xrpld-hooks-testnet
|
||||
```
|
||||
### Starting the container
|
||||
1. Download and install docker: https://docs.docker.com/get-docker/
|
||||
2. Then to run the container interactively use:
|
||||
```bash
|
||||
docker run -d --name xrpld-hooks xrpllabsofficial/xrpld-hooks-testnet
|
||||
docker exec -it xrpld-hooks bash
|
||||
```
|
||||
3. Set up a second terminal to view the log:
|
||||
|
||||
Open a new terminal window on your system and run.
|
||||
```bash
|
||||
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 succeed and what actions the hooks take.
|
||||
Since there is rather a lot of log output you might find it useful to run this with `grep -a <your account>` after you obtain an account you are interested in.
|
||||
E.g. `docker exec -it xrpld-hooks tail -f log | grep -a rEy6oGFEeKNiMUTTEzTDnMVfe7SvcBsHZK`
|
||||
|
||||
4. If you need to kill and destroy the container and restart it (if you are still attached to the container, type `exit` there to quit the container terminal):
|
||||
```bash
|
||||
docker rm -f xrpld-hooks
|
||||
```
|
||||
Then repeat step 2. If you need to fetch a newly published image, check the `Update an existing container` step above.
|
||||
|
||||
### Interacting with the container
|
||||
After following the above steps you will be inside a shell inside the container. Rippled will already be running with the correct settings. Read the README.md in the container for further instructions on installing and interacting with the example hooks.
|
||||
|
||||
## What's in this docker?
|
||||
1. A `rippled` instance connected to the Hooks Public Testnet.
|
||||
2. A compiler toolchain for building hooks (wasmcc, wasm2wat, etc...)
|
||||
3. Example hooks and support scripts to install them on your account.
|
||||
|
||||
## Get testnet XRP
|
||||
The Faucet is on the [main page](https://hooks-testnet.xrpl-labs.com/). Make a note of your secret (family seed) because you will need it for all the examples.
|
||||
|
||||
## Testnet explorer
|
||||
Use the [Testnet Explorer](https://hooks-testnet-explorer.xrpl-labs.com/) to view transactions, accounts and hook state objects as you go.
|
||||
|
||||
## File types
|
||||
1. The example hooks are written in C. Any file ending in `.c` is a hook. Any file ending in `.h` is a header file used by
|
||||
all hooks.
|
||||
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 installing hooks and interacting with the ledger through ripple-lib.
|
||||
|
||||
## Building
|
||||
To build you can run `make` from any hook's directory. The example `makefile` in each directory shows you how to build a hook.
|
||||
|
||||
## Interacting
|
||||
To interact with the example hooks change (`cd`) into one of these directories:
|
||||
- liteacc
|
||||
- firewall
|
||||
- carbon
|
||||
- accept
|
||||
- notary
|
||||
- peggy
|
||||
|
||||
All example hooks are installed by running `node <hook name>.js`. The usage information will be provided at the commandline.
|
||||
|
||||
You can check a reported `SetHook` transaction ID with the [Hooks Testnet Explorer](https://hooks-testnet-explorer.xrpl-labs.com/).
|
||||
|
||||
Finally run the additional `.js` files to interact with the Hook or write your own interaction.
|
||||
|
||||
## Hook API
|
||||
- Documentation for the Hook API can be found at the [Hooks Testnet Site](https://hooks-testnet.xrpl-labs.com/).
|
||||
- For further details check:
|
||||
1. `hook-api-examples/hookapi.h`
|
||||
2. `src/ripple/app/tx/applyHook.h`
|
||||
3. `src/ripple/app/tx/impl/applyHook.cpp`
|
||||
|
||||
## 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](https://hooks-testnet-explorer.xrpl-labs.com/).
|
||||
|
||||
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 `./accept/`
|
||||
|
||||
## Tracing output
|
||||
Output is written to a file in the current working directory called `log`.
|
||||
|
||||
Rippled produces a large amount of output in `trace` mode (which is the default mode used in this example). You may
|
||||
find that you need to scroll back considerably after running a hook or interacting with a hook to find out what
|
||||
precisely happened.
|
||||
|
||||
Greping for the relevant account will help, as all Hooks prepend the otxn account and hook account to the trace line.
|
||||
|
||||
## SetHook Transaction
|
||||
Set a Hook on an activated account using a SetHook Transaction (ttHOOK_SET = 22). This must contain the following fields:
|
||||
- sfAccount
|
||||
- sfCreateCode: Containing the binary of the web assembly
|
||||
- sfHookOn: An unsigned 64bit integer (explained bellow)
|
||||
|
||||
### sfHookOn
|
||||
Each bit in this unsigned int64 indicates whether the Hook should execute on a particular transaction type. All bits are *active low* **except** bit 22 which is *active high*. Since 22 is ttHOOK_SET this means the default value of all 0's will not fire on a SetHook transaction but will fire on every other transaction type. This is a deliberate design choice to help people avoid bricking their XRPL account with a misbehaving hook.
|
||||
|
||||
Bits are numbered from right to left from 0 to 63).
|
||||
|
||||
Examples:
|
||||
|
||||
1. If we want to completely disable the hook:
|
||||
```C
|
||||
~(1ULL << 22) /* every bit is 1 except bit 22 which is 0 */
|
||||
```
|
||||
|
||||
2. If we want to disable the hook on everything except ttPAYMENT:
|
||||
```C
|
||||
~(1ULL << 22) & ~(1ULL)
|
||||
```
|
||||
|
||||
3. If we want to enable the hook on everything except ttHOOK_SET
|
||||
```C
|
||||
0
|
||||
```
|
||||
|
||||
4. If we want to enable hook firing on ttHOOK_SET (dangerous) and every other transaction type:
|
||||
```C
|
||||
(1ULL << 22)
|
||||
```
|
||||
|
||||
|
||||
|
||||
-------
|
||||
Please see [Hooks Testnet V2](https://hooks-testnet-v2.xrpl-labs.com/) for faucet + documentation + explorer + builder.
|
||||
|
||||
# The XRP Ledger
|
||||
|
||||
|
||||
Reference in New Issue
Block a user