Hooks Toolkit

Hooks-Toolkit is a powerful library that allows developers to interact with smart contracts on the Xahau. In this guide, we will walk you through the steps required to set up Hooks-Toolkit in your project.

Quickstart

This guide will get you all set up and ready to use the Hooks Toolkit. We'll cover how to get started using one of our SDK clients and how to make your first SDK request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful features.

Choose your client

Before making your first SDK request, you need to pick which SDK client you will use. Hooks Toolkit offers clients for Typescript/JavaScript, and Python. In the following example, you can see how to install each client.

npm i -g @transia/hooks-toolkit-cli

Initializing Your Project

To quickly set up your project, you can use the init function provided by hooks-toolkit-cli. This command will create a new directory with all the necessary files and configurations for your project.

Run the following command to create a new project:

hooks-toolkit-cli init js myproj

This command will create a directory named myproj with the following structure:

myproj/
├── contracts/
│   ├── base.ts
├── .env
├── package.json
├── tsconfig.json
└── src/
    └── index.ts

Project Structure

• contracts/: This folder contains the JS/C hook files that you will use to define your hooks.
• .env: This file contains environment variables, including your testnet account details, which are automatically generated during initialization.
• package.json: This file contains the project dependencies and scripts.
• tsconfig.json: This file contains TypeScript configuration settings.
• src/: This folder contains the main entry point of your application, index.ts.

Installing Dependencies

After initializing your project, navigate to the myproj directory and install the necessary dependencies:

cd myproj
yarn install

The .env File

The .env file is automatically created during the project initialization and contains environment variables that are used to customize the behavior of the hooks-toolkit library. It includes your testnet account details, which were generated for you.

Here's an example of how the .env file might look:

HOOKS_COMPILE_HOST=https://hook-buildbox.xrpl.org
XRPLD_ENV=testnet
XRPLD_WSS=wss://jshooks.xahau-test.net
ALICE_SECRET=your_generated_secret

The HOOKS_COMPILE_HOST variable is used by the hooks-toolkit-cli to specify the host for building the JS/C hook files. The XRPLD_ENV variable is used by the hooks-toolkit to specify the environment for running the XRPL network.

By default, the HOOKS_COMPILE_HOST is set to https://hook-buildbox.xrpl.org, which is the public API host provided by the Xrpl-Labs team. If you are running your own local instance of the Xrpl-Hooks-Compiler API, you can update the HOOKS_COMPILE_HOST variable to point to your local API host.

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.

Building and Running the Contracts

To build and run the contracts, you can use the following command:

yarn run build
// hooks-toolkit-cli compile contracts/base.ts build/

This command will compile the JS/C hook files and save the wasm files to the build directory.

Deploying Your Smart Contract

In this section, you'll learn how to deploy a smart contract and subsequently trigger it by performing an invoke transaction. This process involves two key steps: first, you'll set up the smart contract on the XRPL network, and then you'll execute a transaction that interacts with the deployed contract.

Step 1: Deploying the Smart Contract

To begin, you'll use the Hooks Toolkit to deploy your smart contract. This is accomplished by creating a hook payload that defines the contract's behavior and then setting the hooks on the XRPL network. The hook payload specifies various parameters, such as the version, namespace, and flags, which dictate how the contract will operate.

Step 2: Triggering the Smart Contract

Once the smart contract is deployed, you can invoke it by sending a transaction that calls the contract's functionality. This is done by constructing an invoke transaction that references the deployed contract. When the transaction is submitted to the XRPL network, it triggers the execution of the smart contract, allowing you to see its effects in action.

Example Code

Here's how you can implement these steps in your code:

yarn run deploy
// yarn run build && ts-node src/index.ts

In the provided code example, you'll see how to connect to the XRPL network, create the hook payload, set the hooks, and then build and submit the invoke transaction. The result of the transaction will include metadata that reveals the outcome of the smart contract execution, allowing you to verify that it has been triggered successfully.

import {
  Client,
  Wallet,
  Invoke,
  SetHookFlags,
  TransactionMetadata,
} from "@transia/xrpl";
import {
  createHookPayload,
  setHooksV3,
  SetHookParams,
  Xrpld,
  ExecutionUtility,
} from "@transia/hooks-toolkit";
import "dotenv/config";

export async function main(): Promise<void> {
  const client = new Client(process.env.XRPLD_WSS || "");
  await client.connect();
  client.networkID = await client.getNetworkID();

  const aliceWallet = Wallet.fromSeed(process.env.ALICE_SEED || "");

  const hook = createHookPayload({
    version: 1, // version 0 for c hooks
    createFile: "base",
    namespace: "base",
    flags: SetHookFlags.hsfOverride,
    hookOnArray: ["Invoke"],
    fee: "100000", // omit for c hooks
  });

  await setHooksV3({
    client: client,
    seed: aliceWallet.seed,
    hooks: [{ Hook: hook }],
  } as SetHookParams);

  const builtTx: Invoke = {
    TransactionType: "Invoke",
    Account: aliceWallet.classicAddress,
  };
  const result = await Xrpld.submit(client, {
    wallet: aliceWallet,
    tx: builtTx,
  });

  const hookExecutions = await ExecutionUtility.getHookExecutionsFromMeta(
    client,
    result.meta as TransactionMetadata
  );
  console.log(hookExecutions.executions[0].HookReturnString);
  await client.disconnect();
}

main();