Skip to main content

​
Overview

Hooks are smart contracts that extend your Gotchipus’s behavior. This guide walks you through building, deploying, and attaching a custom Hook.

​
Prerequisites

  • Solidity development experience
  • Foundry installed (forge, cast)
  • Familiarity with the Hooks concept

​
Step 1: Choose Your Hook Type

The BaseHook contract provides three specialized base contracts:
Base ContractSupports
BeforeExecuteHookOnly beforeExecute events
AfterExecuteHookOnly afterExecute events
FullHookBoth beforeExecute and afterExecute
Choose based on when your logic needs to run.

​
Step 2: Write Your Hook

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.29;

import {AfterExecuteHook, HookParams} from "../hooks/BaseHook.sol";

contract MyRewardHook is AfterExecuteHook {
    constructor(address _gotchipus) AfterExecuteHook(_gotchipus) {}

    function _afterExecute(HookParams calldata params)
        internal
        override
        returns (bytes4)
    {
        // Your logic here
        // params.tokenId — which Gotchipus
        // params.account — the TBA address
        // params.caller  — who initiated
        // params.target  — contract being called
        // params.value   — ETH/PROS sent
        // params.selector — function selector

        return HOOK_SUCCESS;
    }
}

​
Hook Parameters

Every Hook receives a HookParams struct:
FieldTypeDescription
tokenIduint256The Gotchipus NFT token ID
accountaddressThe Gotchipus’s TBA address
calleraddressWho initiated the execution
targetaddressTarget contract being called
valueuint256Native token value being sent
selectorbytes4Function selector being called
hookAddressaddressThis Hook’s own address

​
Return Value

Hooks must return HOOK_SUCCESS (bytes4) to indicate successful execution. Returning any other value or reverting will cause the execution to fail.

​
Step 3: Deploy

forge create src/hooks/MyRewardHook.sol:MyRewardHook \
  --constructor-args <GOTCHIPUS_DIAMOND_ADDRESS> \
  --rpc-url <PHAROS_RPC> \
  --private-key <YOUR_KEY>

​
Step 4: Attach to a Gotchipus

Once deployed, attach your Hook via the HooksFacet: 
cast send <GOTCHIPUS_DIAMOND> \
  "addHook(uint256,address)" \
  <TOKEN_ID> <HOOK_ADDRESS> \
  --rpc-url <PHAROS_RPC> \
  --private-key <YOUR_KEY>
Or use the Terminal’s Hook management tab to attach it through the UI.

​
Step 5: Test

Write Foundry tests to verify your Hook behaves correctly: 
function testMyHookFiresAfterExecute() public {
    // Setup: deploy diamond, mint, summon, add hook
    // Action: execute a transaction through the TBA
    // Assert: verify your hook's effects
}

​
Constraints

  • Maximum 10 Hooks per event per Gotchipus
  • Hooks must be valid contracts implementing the correct interface
  • The onlyGotchipus modifier ensures Hooks can only be called by the Diamond
  • Hooks should be gas-efficient — excessive gas usage impacts execution cost

​
Example Hooks

The codebase includes two reference implementations:
HookFileBehavior
RewardHooksrc/hooks/examples/RewardHook.solDistributes rewards after successful executions
WhitelistHooksrc/hooks/examples/WhitelistHook.solRestricts execution to whitelisted target addresses
Study these as patterns for your own Hooks.

​
Publishing to the Marketplace

After deploying and testing your Hook, you can submit it to the Hook Marketplace for other players to discover and use. Include source code for verification to build trust with the community.