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: Choose based on when your logic needs to run.

Step 2: Write Your Hook

Hook Parameters

Every Hook receives a HookParams struct:

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

Step 4: Attach to a Gotchipus

Once deployed, attach your Hook via the HooksFacet:
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:

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