Documentation Index
Fetch the complete documentation index at: https://docs.gotchipus.com/llms.txt
Use this file to discover all available pages before exploring further.
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 Contract | Supports |
|---|
BeforeExecuteHook | Only beforeExecute events |
AfterExecuteHook | Only afterExecute events |
FullHook | Both beforeExecute and afterExecute |
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 sent
// params.selector — function selector
return HOOK_SUCCESS;
}
}
Hook Parameters
Every Hook receives a HookParams struct:
| Field | Type | Description |
|---|
tokenId | uint256 | The Gotchipus NFT token ID |
account | address | The Gotchipus’s TBA address |
caller | address | Who initiated the execution |
target | address | Target contract being called |
value | uint256 | Native token value being sent |
selector | bytes4 | Function selector being called |
hookAddress | address | This 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 https://mainnet.base.org \
--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 https://mainnet.base.org \
--private-key <YOUR_KEY>
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:
| Hook | File | Behavior |
|---|
| RewardHook | src/hooks/examples/RewardHook.sol | Distributes rewards after successful executions |
| WhitelistHook | src/hooks/examples/WhitelistHook.sol | Restricts execution to whitelisted target addresses |
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.