Hook Payload

The createHookPayload function in the SDK is used to create a payload for a SetHook transaction in the XRPL. 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 '@transia/hooks-toolkit'

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

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 '@transia/hooks-toolkit'

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

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 '@transia/hooks-toolkit'

const hook = createHookPayload({
  version: 2, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: SetHookFlags.hsfOverride, // SetHookFlag
  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 SetHookFlags.hsfOverride:

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

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

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 '@transia/hooks-toolkit'

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

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 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 '@transia/hooks-toolkit'
import {
  xflToHex
} from '@transia/binary-models'

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

const hook = createHookPayload({
  version: 0, // HookApiVersion
  createFile: 'hook_on_tt', // filename in /build
  namespace: 'hook_on_tt', // namespace (ascii)
  flags: SetHookFlags.hsfOverride, // SetHookFlag
  hookOnArray: ['Payment'] // HookOn Transactions
  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 '@transia/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: SetHookFlags.hsfOverride, // SetHookFlag
  hookOnArray: ['Payment'] // HookOn Transactions
  hookGrants: [hook2Grant1.toXrpl()], // HookGrants
})

Note that the available transaction types for the hookOnArray parameter and the structure of the hookParams and hookGrants objects are defined in the XRPL documentation.

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 the XRPL.