HookCanEmit, an Extra Step Towards Making Xahau a Safer Place

Welcome to a new chapter of Learning Xahau, a space where you’ll find in-depth articles about Xahau—both theoretical and practical—designed for all audiences. If this is your first time here and you want to learn the basics, I recommend checking out the first article in the Learning Xahau series.

Today we’re talking about HookCanEmit, a new optional parameter we can use when installing Hooks. If you’re not familiar with Hooks or Xahau, I’ll start with a brief introduction.

Xahau is an independent decentralized blockchain based on the XRP Ledger codebase. What makes Xahau special is the introduction of innovations not available on the XRP Ledger, such as Hooks—a technology that enables the creation of smart contracts in a simpler, safer, and regulation-friendly way compared to the EVM vision.

Hooks are pieces of code you can write yourself or use from other users on the network. To make your Hook available on Xahau, you must first go through a process called Create, where the Hook is uploaded to Xahau for the first time. This creates a HookHash, an ID that you can share if you want others to install it. Once a Hook is created, any further use of it is considered an Install operation. Both Create and Install operations use the SetHook transaction, but it’s important to distinguish between them if you ever need help or need to explain where you're stuck.

Since we're talking about Hooks, it’s worth noting that Hooks do not exist independently in Xahau—they are installed on Xahau accounts. Each account can have up to 10 Hooks installed. Think of Hooks as plug-ins that give Xahau accounts new behaviors—they gain “superpowers” that let them react to specific transaction types in ways they normally wouldn’t.

Back to installing Hooks: you may have guessed that to install a third-party Hook, you’ll need its HookHash. HookHashes look something like this: 610F33B8EBF7EC795F822A454FB852156AEFE50BE0CB8326338A81CD74801864.

Although some developers may publish their source code and you can compile the file to see if you get the same HookHash to confirm that it is the same code the developer shows you, it may happen that a user does not have access to the source code of a Hook they want to install. This could occur for many reasons: it's impossible to locate the hook's creator or their repository, the creator does not want someone to copy the hook's logic because it is part of their business or they charge a fee and don't want others to remove the commission request from the business. Contractually, the developed hook is not allowed to be published, and many other reasons. So it is possible that a user finds themselves in the dilemma of whether or not to install a hook. They could be guided by the creator's reputation or the popularity of the hook, but they can never be 100% sure that the code does what it says or that the code only does what it claims to do.

HookCanEmit, the reason for this article, adds an extra optional security step for when you need to install a Hook. HookCanEmit is one of the latest improvements added in Xahau in the 2025.5.1-release+1762 release of the xahaud software. HookCanEmit allows the user to decide what type of transactions they want to allow when this Hook is executed. It is similar to the HookOn parameter, which indicates what type of transactions the Hook should be triggered by. More info: https://docs.xahau.network/concepts/hookon-field

If I want to install a hook (whose code I cannot verify or do not understand the source code) that automates NFT minting processes, what I do not expect (or want) is for the hook to send payments out of my account without me knowing, or create buy or sell offers for tokens, which are other types of transactions the account can generate. Therefore, if we use the HookCanEmit field, we could block these types of transactions and only allow NFT creation. This avoids erroneous or malicious behaviors that someone could introduce into their hooks.

You can generate a HookCanEmit value using Richard Holland’s calculator: https://richardah.github.io/xrpl-hookon-calculator/

As we can see in the image, if we want our Hook to only be able to emit transactions of the Payment type, we should check the option and copy the result provided by the page. In this case, we click PAYMENT and the result is this code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE (ignore 0x part)

If we want it to only work with the NFT minting transaction, we select URITOKEN_MINT and it results in the following code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDFBFFFFF (ignore 0x part)

Time to Get Hands-On

First Test, blocking all types of transactions that can be emitted

Let's confirm that what we say is true. For this, I will use my Forwarder Hook that serves to forward a payment that enters the account where this hook is installed. We use this hook because by its nature it will have to emit a Payment transaction if it receives funds and has configured addresses to which to forward this money. In the Xahau Testnet, I created the account rMLRy72cWuPgCBxjni7e84ThuwRsBDta9p and install the hook adding the HookCanEmit FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF to prevent the hook from emitting, since with this code we do not allow any type of emission.

"TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "319E16820BAEF9A08C51F52C97338D4CF09E6E53991B4131820A079721C64EA1",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFF7FFFFFBFFFFE",
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF",
          }
        }
      ],
      ...networkInfo.txValues,

We confirm that the transaction has been successful in XRPLWin: https://xahau-testnet.xrplwin.com/tx/31F8C8948C678347CDFC25CC2C59608BD413778BEDDB9B61435F7F6B3111D90C#overview

The Forwarder Hook needs to pre-configure an address to which we want to forward what enters the account where we are installing the hook, so we are going to configure this one: rf1NrYAsv92UPDd8nyCG4A3bez7dhYE61r which using the XRPL Hex Visualizer tells us that in Hex it would be 4B50699E253C5098DEFE3A0872A79D129172F496. We can use this transaction:

TransactionType: "Invoke",
      Account: your_address,
      Flags: 0,
      HookParameters: [
        {
          HookParameter: {
            HookParameterName: "414444",
            HookParameterValue: "D53F733E54B866B9FBDB85762071832B03A56C76",
          },
        },
        {
          HookParameter: {
            HookParameterName: "4E554D",
            HookParameterValue: "00",
          },
        },
      ],
      ...networkInfo.txValues,

We execute the transaction and check that everything went well; we should receive a message that the address has been added like this: https://xahau-testnet.xrplwin.com/tx/4F8B247877BFC44B033C14ED1C5945B395F95C38261AB2FA2067D782BAD94043

Now the acid test: let's check that HookCanEmit works as expected. The account rMLRy72cWuPgCBxjni7e84ThuwRsBDta9p should not allow the Forwarder Hook to emit an outgoing transaction from the account. Let's see. The account receives a payment of 1 XAH from the account rBHk1ekqaVkKzkrsivbajrw5ZE3omR23Ax but was not able to emit the money forwarding to the account rf1NrYAsv92UPDd8nyCG4A3bez7dhYE61r as the hook was expected to do.

In fact, the hook believes that the execution was correct, emitting the forwarding transaction and returning a success message, but our "firewall" HookCanEmit stopped the transaction. Here you can see how the hook thinks everything went fine.

Second test, let's allow it to emit payments.

In this case, we are going to delete the hook and reinstall it. That way we learn more operations with this test. Here would be the transaction that uninstalls the hook:

      "TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      Hooks:
    [        
        {                        
            Hook: {
                CreateCode: "",
                Flags: 1,
            }
        }
    ],
      ...networkInfo.txValues,

Here we can confirm that the hook has been uninstalled: https://xahau-testnet.xrplwin.com/tx/B8E94645D10E403ABA60525372208BDA90248C14118231E7047174AA7E233533

Now we are going to install the hook again but granting permission for Payment transactions. To do this, we go to the calculator https://richardah.github.io/xrpl-hookon-calculator/ and activate the Payment button, which results in this code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE. Remember to ignore the 0x.

We generate a SetHook transaction to install the hook with permission in HookCanEmit for Payment emissions:

"TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "319E16820BAEF9A08C51F52C97338D4CF09E6E53991B4131820A079721C64EA1",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFF7FFFFFBFFFFE",
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE",
          }
        }
      ],
      ...networkInfo.txValues,

Once installed, we can go check the transaction on XRPLWin and confirm that we have done it correctly. https://xahau-testnet.xrplwin.com/tx/0A2F2243963533F716A1D11C08786B41AE366E7CD5753AA7EB4B9D7EEF0555D9. If we click on the Information block in the Summary, we see the "Allowed emission types" section where the transaction type ttPayment is marked as valid.

Everything is ready, let's send a transaction to the hook's account to see if now it is able to forward it. If you deleted the namespace, remember you will have to repeat the process of adding a forwarding account for the forwarder hook. If you followed the steps just like I did, you won’t have to do it.

This time, HookCanEmit allows us to perform payment emissions from the hook, so the operation was completed.

Final words and code

As you can see, HookCanEmit is an extra step that all Xahau users can use to avoid surprises or unexpected behavior. Just as we should have digital hygiene with our passwords on the Internet, we must also make responsible use of the configuration of the hooks we install in order to work more securely and enjoy the opportunities Xahau offers us.

The code used in this article is available at: https://github.com/Ekiserrepe/Xahau-HookCanEmit-Example in case you need it.

Feel free to reach out with questions, or join the Xahau Contributors Discord server, where we’ll be happy to help.

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account