The Hooks Toolkit (Typescript)

The Hooks-Toolkit is a powerful library that allows developers to interact with smart contracts on the Xahau.

Table of Contents

• Installation
• Set Hook
• Hook Payload
• State Utility
• Execution Utility
• Submit Tx
• Validate Hook

Installation

To use the binary-models repo, you can install the package via npm or yarn or pnpm:

pnpm add @xahau/hooks-toolkit

Set Hook

The setHooks function in the SDK is used to set hooks on Xahau. It takes in a SetHookParams object as a parameter, which includes the client, seed, and hooks to be set.

Setting Hooks with setHooks

To set a hook on Xahau using the setHooks function, you need to provide the following parameters:

• client: Xahau client object.
• seed: The seed of the account that will set the hook.
• hooks: An array of hook objects to be set.

Each hook object in the hooks array should have the following properties:

• Hook: The hook payload object.

Here is an example of setting a hook using the setHooks function:

import { HookFlags } from 'xahau/dist/npm/models/common/xahau'
import {
  setHooks,
  createHookPayload,
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Invoke'] // Transaction types to trigger on
  hookCanEmitArray: ['Invoke'] // Transaction types to allow to be emitted from the hook
})

await setHooks({
  client: testContext.client,
  wallet: testContext.hook1,
  hooks: [{ Hook: hook }],
})

In the example above, we create a hook payload using the createHookPayload function and set the hook_on field to trigger on the Invoke transaction type. We then pass the hook payload as an object in the hooks array to the setHooks function.

Note that the setHooks function is an asynchronous function and returns a Promise. You can use await to wait for the function to complete.

Deleting Hooks with clearAllHooks

To delete all hooks on Xahau using the clearAllHooks function, you need to provide the following parameters:

• client: Xahau client object.
• seed: The seed of the account that will remove the hook.

Here is an example of deleting all hooks using the clearAllHooks function:

import {
  clearAllHooks,
} from '@xahau/hooks-toolkit'

await clearAllHooks({
  client: testContext.client,
  seed: testContext.hook1.seed,
})

Deleting a single hook with setHooks

To delete a single hook and state on Xahau using the setHooks function, you need to provide the following parameters:

• client: Xahau client object.
• seed: The seed of the account that will delete the hook.
• hooks: An array of hook objects to be deleted.

Here is an example of deleting a single hook for the hook in position 2 using the setHooks function:

import { HookFlags } from 'xahau/dist/npm/models/common/xahau'
import {
  createHookPayload,
  setHooks,
} from '@xahau/hooks-toolkit'

const clearHook = createHookPayload({
  namespace: 'mynamespace', // namespace (ascii)
  flags: HookFlags.hsfOverride | HookFlags.hsfNSDelete, // HookFlags
})
await setHooks({
  client: testContext.client,
  wallet: testContext.hook1,
  hooks: [{Hook: {}}, { Hook: clearHook }],
})

export const metadata = { title: 'Hook Payload', description: 'In this guide, we will talk about what happens when something goes wrong while you work with the API.', }

Hook Payload

The createHookPayload function in the SDK is used to create a payload for a SetHook transaction in Xahau. It takes in several parameters to customize the hook payload.

Hook API Version

The version parameter is used to set the Hook API version. It is an optional parameter and can be set to a number. Here is an example of creating a hook payload with the Hook API version set to 0:

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
})

Create Code

The createFile parameter is used to set the create code for the hook. It is an optional parameter and can be set to a string. Here is an example of creating a hook payload with the create code set to 'hook_on_tt':

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
})

Hook Namespace

The namespace parameter is used to set the hook namespace. It is an optional parameter and can be set to a string. Here is an example of creating a hook payload with the hook namespace set to 'hook_on_tt':

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // HookOn Transactions
})

Hook Flags

The flags parameter is used to set the hook flags. It is an optional parameter and can be set to a number. Here is an example of creating a hook payload with the hook flags set to HookFlags.hsfOverride:

import {
  createHookPayload,
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
})

Hook On Transaction Types

The hookOnArray parameter is used to specify which transaction types a hook should be triggered on. It is an optional parameter and should be passed as an array of strings. Here is an example of creating a hook payload with the hookOnArray set to trigger on the Payment transaction type:

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
  // or you can use the following fields
  // hookOnIncomingArray: ['Payment'] // Transaction types to trigger on incoming transactions
  // hookOnOutgoingArray: ['Invoke']  // Transaction types to trigger on outgoing transactions, needs to be different from hookOnIncomingArray.
})

To create a hook that triggers on multiple transaction types, the hookOnArray should be set to an array of those types, such as ['Payment', 'EscrowFinish'].

Hook Can Emit Transaction Types

The hookCanEmitArray parameter is used to specify which transaction types a hook should be allowed to emit. It is an optional parameter and should be passed as an array of strings. Here is an example of creating a hook payload with the hookCanEmitArray set to allow the Payment transaction type to be emitted from the hook:

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
  hookCanEmitArray: ['Payment'] // Transaction types to allow to be emitted from the hook
})

To create a hook that allows multiple transaction types to be emitted from the hook, the hookCanEmitArray should be set to an array of those types, such as ['Payment', 'EscrowFinish'].

Hook Parameters

The hookParams parameter is used to set the hook parameters. It is an optional parameter and should be passed as an array of HookParameter objects. Each HookParameter object consists of a HookParamName and a HookParamValue. Here is an example of creating a hook payload with a hook parameter:

import {
  createHookPayload,
  iHookParamEntry,
  iHookParamName,
  iHookParamValue,
} from '@xahau/hooks-toolkit'
import { floatToLEXfl } from '@transia/binary-models'

const param1 = new iHookParamEntry(
  new iHookParamName('TEST'),
  new iHookParamValue(floatToLEXfl('10'), true)
)

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
  hookParams: [param1.toXrpl()], // HookParameters
})

Hook Grants

The hookGrants parameter is used to set the hook grants. It is an optional parameter and should be passed as an array of HookGrant objects. Each HookGrant object consists of a HookGrantHash and a HookGrantAuthorize. Here is an example of creating a hook payload with a hook grant:

import {
  createHookPayload,
  iHookGrantEntry,
  iHookGrantHash,
  iHookGrantAuthorize
} from '@xahau/hooks-toolkit'

const hook2Grant1 = new iHookGrantEntry(
  new iHookGrantHash(hookHash as string),
  new iHookGrantAuthorize(carolWallet.classicAddress)
)

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // HookOn Transactions
  hookGrants: [hook2Grant1.toXrpl()], // HookGrants
})

Hook Name

The hookName parameter is used to set the hook name. It is an optional parameter and can be set to a string. Here is an example of creating a hook payload with the hook name set to 'hook_on_tt':

import {
  createHookPayload
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Payment'] // Transaction types to trigger on
  hookGrants: [hook2Grant1.toXrpl()], // HookGrants
  hookName: 'save_name', // HookName
})

Reference

export interface SetHookPayload {
  version?: number | null
  hookHash?: string | null
  createFile?: string | null
  namespace?: string | null
  flags?: number | 0
  hookOnArray?: string[] | null
  hookParams?: HookParameter[] | null
  hookGrants?: HookGrant[] | null
}
export function createHookPayload(payload: SetHookPayload): iHook

Parameters

• version (optional): The Hook API version. Defaults to 0.
• createFile (optional): The create code for the hook.
• namespace (optional): The hook namespace.
• flags (optional): The hook flags.
• hookOnArray (optional): An array of transaction types that the hook should be triggered on.
• hookParams (optional): An array of hook parameters.
• hookGrants (optional): An array of hook grants.

Return Value

• Returns a HookPayload object that represents the hook payload for a SetHook transaction in Xahau.

State Utility

The StateUtility class in the SDK provides utility functions for working with hook states in Xahau. It includes functions to retrieve hook states, hook definitions, and hook state directories.

Retrieving Hook State

The getHookState function is used to retrieve the state of a hook in Xahau. It takes in the following parameters:

• client: Xahau client object.
• account: The account that owns the hook.
• key: The key of the hook state.
• namespace: The namespace of the hook state.

Here is an example of retrieving the state of a hook:

import {
  serverUrl,
  setupClient,
  StateUtility,
  hexNamespace,
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const hookState = await StateUtility.getHookState(
  testContext.client,
  'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
  'state_key',
  hexNamespace('hook_namespace')
)

console.log(hookState)

Retrieving Hook Definition

The getHookDefinition function is used to retrieve the definition of a hook in Xahau. It takes in the following parameters:

• client: Xahau client object.
• hash: The hash of the hook definition.

Here is an example of retrieving the definition of a hook:

import {
  serverUrl,
  setupClient,
  StateUtility
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const hookDefinition = await StateUtility.getHookDefinition(
  testContext.client,
  'hook_definition_hash'
)

console.log(hookDefinition)

Retrieving Hook State Directory

The getHookStateDir function is used to retrieve the directory of hook states for a specific account and namespace in Xahau. It takes in the following parameters:

• client: Xahau client object.
• account: The account that owns the hook states.
• namespace: The namespace of the hook states.

Here is an example of retrieving the directory of hook states:

import {
  serverUrl,
  setupClient,
  StateUtility,
  hexNamespace
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const hookStateDir = await StateUtility.getHookStateDir(
  testContext.client,
  'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
  hexNamespace('hook_namespace')
)

console.log(hookStateDir)

Execution Utility

The ExecutionUtility class in the SDK provides utility functions for working with hook executions and emitted transactions in Xahau.

Getting Hook Executions from Transaction Metadata

The getHookExecutionsFromMeta function is used to retrieve hook executions from transaction metadata. It takes in the following parameters:

• client: Xahau client object.
• meta: The transaction metadata object.

Here is an example of using the getHookExecutionsFromMeta function:

import { TransactionMetadata } from 'xahau'
import {
  serverUrl,
  setupClient,
  ExecutionUtility 
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const meta: TransactionMetadata = {}

const hookExecutions = await ExecutionUtility.getHookExecutionsFromMeta(
  testContext.client, 
  meta
)

Getting Hook Executions from Transaction Hash

The getHookExecutionsFromTx function is used to retrieve hook executions from a transaction hash. It takes in the following parameters:

• client: Xahau client object.
• hash: The transaction hash.

Here is an example of using the getHookExecutionsFromTx function:

import {
  serverUrl,
  setupClient,
  ExecutionUtility 
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const hash = '...'

const hookExecutions = await ExecutionUtility.getHookExecutionsFromTx(
  testContext.client,
  hash
)

Getting Hook Emitted Transactions from Transaction Metadata

The getHookEmittedTxsFromMeta function is used to retrieve hook emitted transactions from transaction metadata. It takes in the following parameters:

• client: Xahau client object.
• meta: The transaction metadata object.

Here is an example of using the getHookEmittedTxsFromMeta function:

import { TransactionMetadata } from 'xahau'
import {
  serverUrl,
  setupClient,
  ExecutionUtility 
} from '@xahau/hooks-toolkit'

const testContext = (await setupClient(
  serverUrl
)) as XrplIntegrationTestContext

const meta: TransactionMetadata = ...

const hookEmittedTxs = await ExecutionUtility.getHookEmittedTxsFromMeta(
  testContext.client,
  meta
)

Submit Tx

The Xrpld.submit function in the SDK is used to submit a transaction to Xahau. It takes in a SubmitTxParams object as a parameter, which includes the client, wallet, and transaction to be submitted.

Submitting a Transaction with submitTx

To submit a transaction to Xahau using the Xrpld.submit function, you need to provide the following parameters:

• client: Xahau client object.
• wallet: The wallet object that holds the account information for the transaction.
• tx: The transaction object to be submitted.

Here is an example of submitting a transaction using the Xrpld.submit function:

import {
  Xrpld,
  createHookPayload,
  setHooks,
  HookFlags
} from '@xahau/hooks-toolkit'

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: HookFlags.hsfOverride, // HookFlags
  hookOnArray: ['Invoke'] // Transaction types to trigger on
  hookCanEmitArray: ['Invoke'] // Transaction types to allow to be emitted from the hook
})

await setHooks({
  client: testContext.client,
  wallet: testContext.alice,
  hooks: [{ Hook: hook }],
})

const aliceWallet = testContext.alice
const bobWallet = testContext.bob
const builtTx: Invoke = {
  TransactionType: 'Invoke',
  Account: bobWallet.classicAddress,
  Destination: aliceWallet.classicAddress,
}

const result = Xrpld.submit(testContext.client, {
  wallet: bobWallet,
  tx: builtTx,
} as SubmitTxParams)

Validate Hook

The validateHook function calls the hook_validate RPC to check a hook's WASM against the node's guard and gas rules without installing it. It takes the client and either createFile (filename in /build) or code (WASM as hex). The result contains valid, the instruction counts, vm_error when present, and the validator log lines, all of which are also logged. The RPC is enabled by default only on standalone nodes; on other nodes it returns notSupported unless [hook_validate_rpc] is set in xahaud.cfg.

import { validateHook } from '@xahau/hooks-toolkit'

const result = await validateHook({ client, createFile: 'hook_on_tt' })
console.log(result.valid)
console.log(result.log)