@gotchipus/sdk

Official SDK for building Gotchipus Hooks - interfaces, base contracts, and utilities.

Installation

# npm
npm install @gotchipus/sdk

# yarn
yarn add @gotchipus/sdk

# pnpm
pnpm add @gotchipus/sdk

# Foundry
forge install gotchipus/sdk

Quick Start

Option 1: Implement IHook Interface (Minimal)

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

import { IHook } from "@gotchipus/sdk/contracts/interfaces/IHook.sol";

contract MyHook is IHook {
    bytes4 private constant HOOK_SUCCESS = 0x378e142e;

    function getHookPermissions() external pure override returns (Permissions memory) {
        return Permissions({ beforeExecute: true, afterExecute: false });
    }

    function beforeExecute(HookParams calldata params) external override returns (bytes4) {
        // Your custom logic here
        require(params.value < 1 ether, "Value too high");
        return HOOK_SUCCESS;
    }

    function afterExecute(HookParams calldata) external pure override returns (bytes4) {
        revert("Not implemented");
    }
}

Option 2: Extend BaseHook (Recommended)

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

import { BeforeExecuteHook } from "@gotchipus/sdk/contracts/base/BaseHook.sol";
import { IHook } from "@gotchipus/sdk/contracts/interfaces/IHook.sol";

contract MyHook is BeforeExecuteHook {
    constructor(address _gotchipus) BeforeExecuteHook(_gotchipus) {}

    function _beforeExecute(IHook.HookParams calldata params) internal view override {
        // Your custom logic here
        require(params.value < 1 ether, "Value too high");
        // No need to return - BaseHook handles it
    }
}

Available Contracts

Interfaces

| Contract | Description | |----------|-------------| | IHook | Core interface that all hooks must implement |

Base Contracts

| Contract | Description | |----------|-------------| | BaseHook | Abstract base with safety checks | | BeforeExecuteHook | For hooks that only run before execution | | AfterExecuteHook | For hooks that only run after execution | | FullHook | For hooks that run before and after execution |

Libraries

| Contract | Description | |----------|-------------| | HookConstants | Common constants (HOOK_SUCCESS, etc.) | | HookErrors | Custom error definitions |

Hook Types

BeforeExecuteHook

Runs before the account executes a transaction. Use cases:

• Access control / whitelisting
• Spending limits
• Transaction validation
• Rate limiting

contract WhitelistHook is BeforeExecuteHook {
    mapping(address => bool) public whitelist;

    constructor(address _gotchipus) BeforeExecuteHook(_gotchipus) {}

    function _beforeExecute(IHook.HookParams calldata params) internal view override {
        require(whitelist[params.to], "Target not whitelisted");
    }
}

AfterExecuteHook

Runs after the account executes a transaction. Use cases:

• Reward distribution
• Event logging
• State updates based on results

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

    function _afterExecute(IHook.HookParams calldata params) internal override {
        if (params.success) {
            // Distribute rewards
        }
    }
}

FullHook

Runs both before and after execution. Use cases:

• Comprehensive logging
• Complex state management
• Gas metering

contract LoggerHook is FullHook {
    constructor(address _gotchipus) FullHook(_gotchipus) {}

    function _beforeExecute(IHook.HookParams calldata params) internal override {
        emit ExecutionStarted(params.tokenId, params.to);
    }

    function _afterExecute(IHook.HookParams calldata params) internal override {
        emit ExecutionCompleted(params.tokenId, params.success);
    }
}

HookParams Reference

struct HookParams {
    uint256 tokenId;    // Gotchipus NFT token ID
    address account;    // ERC6551 token-bound account
    address caller;     // Transaction initiator
    address to;         // Target contract/address
    uint256 value;      // ETH value
    bytes4 selector;    // Function selector
    bytes hookData;     // Full calldata
    bool success;       // Execution result (afterExecute only)
    bytes returnData;   // Return data (afterExecute only)
}

Foundry Setup

Add to remappings.txt:

@gotchipus/sdk/=node_modules/@gotchipus/sdk/

Or install via forge:

forge install gotchipus/sdk

Then add remapping:

@gotchipus/sdk/=lib/sdk/

Hardhat Setup

Works out of the box with npm imports:

import "@gotchipus/sdk/contracts/interfaces/IHook.sol";

Security Considerations

1. Always validate permissions - Ensure your hook's getHookPermissions() matches implemented functions
2. Use onlyGotchipus modifier - BaseHook includes this; implement it if using IHook directly
3. Handle failures gracefully - Consider what happens if your hook reverts
4. Gas limits - Be mindful of gas consumption in hooks

Examples

See the examples directory for complete hook implementations:

• WhitelistHook - Address whitelisting
• SpendingLimitHook - Daily spending limits
• RewardDistributorHook - Post-execution rewards
• ExecutionLoggerHook - Comprehensive logging

Contributing

Contributions are welcome! Please read our Contributing Guide first.

License

MIT License - see LICENSE for details.

Links

• Documentation
• Discord
• X