> ## 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.

# Build a Hook

> Create custom behavioral modules for Gotchipus

## 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](/ai-and-autonomy/hooks)

## 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` |

Choose based on when your logic needs to run.

## Step 2: Write Your Hook

```solidity theme={null}
// 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

```bash theme={null}
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`:

```bash theme={null}
cast send <GOTCHIPUS_DIAMOND> \
  "addHook(uint256,address)" \
  <TOKEN_ID> <HOOK_ADDRESS> \
  --rpc-url https://mainnet.base.org \
  --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:

```solidity theme={null}
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 |

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](/ai-and-autonomy/hook-marketplace) for other players to discover and use. Include source code for verification to build trust with the community.