Learn how to get the hooks-toolkit set up in your project.

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:

• Docker Installation Guide

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:

1. Navigate to the Issues section of the repository.
2. Click on the "New issue" button.
3. Fill out the issue template with relevant information, including a clear and concise description of the problem or question.
4. 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:

• Stack Overflow

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.