Introduction
Getting started
Learn how to get the hooks-toolkit set up in your project.
Installation
Step-by-step guides to setting up your system and installing the library.
Development Environments
Run a standalone or mini cluster plus an explorer for testing and development.
Hook Payload
Create custom hooks in the XRPL with `createHookPayload`.
State Utils
State Utils allow you to retrieve hook states.
Quick start
Hooks-Toolkit is a powerful library that allows developers to interact with smart contracts on the XRPL. In this guide, we will walk you through the steps required to set up Hooks-Toolkit in your project.
Installing Global dependencies
To install global dependencies, you'll need to have Node.js, Npm, Python3 and Pip3 installed on your system. Once you have these dependencies installed, you can install the global dependencies using the following command:
npm i -g yarn c2wasm-cli
pip3 install xrpld-netgen
Before you can start the development environments, you'll need to have Docker installed on your system. Docker is a platform that allows you to build, package, and distribute applications as lightweight containers.
To install Docker, please refer to the official Docker documentation for your operating system:
Follow the instructions provided in the documentation to install Docker on your machine.
Once Docker is installed, you can proceed with starting the development environment as mentioned in the previous section.
Installing dependencies
To install hooks-toolkit, you'll need to have Node.js and Yarn installed on your system. Once you have these dependencies installed, you can install hooks-toolkit in your Xrpl project using the following command:
yarn add @transia/hooks-toolkit ts-node typescript @tsconfig/node16
Add tsconfig
{
"extends": "@tsconfig/node16/tsconfig.json",
"compilerOptions": {
"jsx": "react",
"composite": true,
"module": "commonjs",
"moduleResolution": "node",
"sourceMap": true,
"strict": true,
"pretty": true,
"declaration": true,
"declarationMap": true,
"strictNullChecks": false,
"noImplicitAny": true,
"noUnusedLocals": true,
"removeComments": true,
"preserveConstEnums": true,
"esModuleInterop": true,
"skipLibCheck": false,
"resolveJsonModule": true,
"preserveSymlinks": true,
}
}
Creating a .env file
To configure your project, you can create a .env
file in the root directory of your project. This file will contain environment variables that are used to customize the behavior of the hooks-toolkit library.
Here's an example of how the .env
file might look:
C2WASM_CLI_HOST=https://hook-buildbox.xrpl.org
RIPPLED_ENV=standalone
The C2WASM_CLI_HOST
variable is used by the c2wasm-cli
to specify the host for building the C hook files. The RIPPLED_ENV
variable is used by the xrpld-netgen
to specify the environment for running the XRPL network.
By default, the C2WASM_CLI_HOST
is set to https://hook-buildbox.xrpl.org
, which is the public API host provided by the Hooks-Toolkit team. If you are running your own local instance of the Hooks-Toolkit API, you can update the C2WASM_CLI_HOST
variable to point to your local API host.
The RIPPLED_ENV
variable is set to standalone
by default, which is the environment used by the xrpld-netgen
to run a standalone XRPL network. If you are using a different environment, such as testnet
or mainnet
, you can update the RIPPLED_ENV
variable accordingly.
Make sure to save the .env
file in the root directory of your project and include it in your version control system's ignore file (e.g., .gitignore
) to prevent sensitive information from being exposed.
Once you have created the .env
file, the hooks-toolkit library will automatically load the environment variables when it is initialized in your project.
Starting the Developer Environment
To start the standalone environment, you can use the following command:
xrpld-netgen up:standalone
The up:standalone
command will build and recreate the Docker containers defined in the docker-compose.yml
file. The -d
flag runs the containers in detached mode, allowing them to run in the background.
Once the containers are up and running, the xrpld-netgen will create a xrpld
directory in the current working directory. This directory contains the configuration files, logs, database, and validator list for the xrpld-netgen standalone network.
Accessing the Standalone Environment
To access the standalone environment, you can use the following URLs and ports:
- Rippled API:
http://localhost:80
- Rippled WebSocket:
ws://localhost:80
- Explorer:
http://localhost:4000
Setting up the Contracts Folder
To interact with the hooks-toolkit from your JavaScript client application, you'll first need to set up a folder named contracts
that holds the C hook files. This folder will contain the necessary code for your hooks.
In the contracts
folder, create a new file named base.c
and copy the following code into it:
/**
*
*/
#include "hookapi.h"
int64_t hook(uint32_t reserved) {
TRACESTR("Base.c: Called.");
accept(SBUF("base: Finished."), __LINE__);
_g(1,1);
// unreachable
return 0;
}
This code represents a basic hook implementation. You can modify it to suit your specific needs.
Building and Running the Contracts
To build and run the contracts, you can use the following command:
c2wasm-cli contracts build
This command will compile the C hook files and save the wasm files to the build
directory.
Creating the standalone.ts File
Next, we will create a file named standalone.ts
in the project src
directory. This file will contain the code that imports and initializes the necessary components from the hooks-toolkit library.
Here's an example of how the standalone.ts
file might look:
import {
Payment,
SetHookFlags,
TransactionMetadata,
xrpToDrops,
} from '@transia/xrpl'
import {
createHookPayload,
setHooksV3,
SetHookParams,
Xrpld,
ExecutionUtility,
} from '@transia/hooks-toolkit'
import {
XrplIntegrationTestContext,
serverUrl,
setupClient,
} from '@transia/hooks-toolkit/dist/npm/src/libs/xrpl-helpers'
export async function main(): Promise<void> {
// Initialize the XRPL test context
const testContext = (await setupClient(
serverUrl
)) as XrplIntegrationTestContext
// Create a hook payload
const hook = createHookPayload({
version: 0,
createFile: 'base',
namespace: 'base',
flags: SetHookFlags.hsfOverride,
hookOnArray: ['Payment']
})
// Set the hooks
await setHooksV3({
client: testContext.client,
seed: testContext.hook1.seed,
hooks: [{ Hook: hook }],
} as SetHookParams)
// PAYMENT IN
const aliceWallet = testContext.alice
const hookWallet = testContext.hook1
// Build the payment transaction
const builtTx: Payment = {
TransactionType: 'Payment',
Account: aliceWallet.classicAddress,
Destination: hookWallet.classicAddress,
Amount: xrpToDrops(10),
}
// Test the hook transaction
const result = await Xrpld.submit(testContext.client, {
wallet: aliceWallet,
tx: builtTx,
})
// Get the hook executions from the transaction metadata
const hookExecutions = await ExecutionUtility.getHookExecutionsFromMeta(
testContext.client,
result.meta as TransactionMetadata
)
// Log the hook return string
console.log(hookExecutions.executions[0].HookReturnString)
// Disconnect from the XRPL test context
await testContext.client.disconnect()
}
// Call the main function
main()
Building and Running the Contracts
To compile the contracts and run the standalone.ts file, you can use the following command:
c2wasm-cli contracts build && ts-node src/standalone.ts
This command will compile the C hook files and execute the standalone.ts
file, which contains the code to interact with the hooks-toolkit.
Examples
Examples of Contracts
If you're looking for examples of contracts that use Hooks-Toolkit, you can find them in the Hooks-Toolkit Contracts. The repository contains a collection of sample contracts that demonstrate various use cases and functionalities. You can explore these examples to get a better understanding of how to implement Hooks-Toolkit in your own projects.
Example Project
To see Hooks-Toolkit in action and get a better understanding of how it can be integrated into a real-world project, you can check out the Hooks-Toolkit Example Project on GitHub. This project provides a comprehensive example of how to set up and use Hooks-Toolkit in a complete application. You can explore the code, run the project, and see how Hooks-Toolkit can be utilized to interact with smart contracts on the XRPL.
Getting help
If you have any questions or issues related to this project, please don't hesitate to ask for help. There are several ways to get support:
Submit an issue
If you have encountered a problem or have a question, the best way to get help is by submitting an issue to the project's GitHub repository. To do so, please follow these steps:
- Navigate to the Issues section of the repository.
- Click on the "New issue" button.
- Fill out the issue template with relevant information, including a clear and concise description of the problem or question.
- Click "Submit new issue".
A member of the project team will review your issue and provide assistance as soon as possible. Please be respectful and patient as we work to address your concerns.
Get help from the community
If you would like to receive support from the larger community, you can post your question on a relevant forum or message board. Some popular options include:
When posting your question, please provide as much detail as possible, including any error messages or logs that may help others troubleshoot the issue.
Contact the project maintainers
If you have a question or concern that you would like to address directly with the project maintainers, you can contact us via email at support@transia.co. We will do our best to respond in a timely manner, but please understand that we may not be able to provide immediate assistance.
Thank you for using our project, and we hope that this information helps you get the support you need.