Smart Contracts

All HookOS contracts are deployed as UUPS upgradeable proxies using OpenZeppelin v5. This page covers contract architecture, deployment addresses, and the upgrade process.

Architecture

The protocol consists of six core contracts that work together:

Base mainnet

Sepolia testnet addresses

{
  "network": "sepolia",
  "chainId": 11155111,
  "deployer": "0xDEF1215EB076DE550ABbca4BE4F5F3CA200dEAdD",
  "contracts": {
    "FeeRouter":    { "proxy": "0x036Ee7de1d12e48FD91E29ab39ff7ee346bcf076" },
    "HookRegistry": { "proxy": "0xffbFf8e267A4c8700DAB9C228b5D4ea595f142F7" },
    "HookManager":  { "proxy": "0xD3278C9E7084EFc92F2ba3D4644A77c2AFDAA42E" },
    "TokenFactory": { "proxy": "0x68DEBbC46d85963C0074E7553c73E39231819038" },
    "Arena":        { "proxy": "0x16Fc3DcB1Fe14216EbDc8dFe75534A3B5E559be4" },
    "Events":       { "proxy": "0x00E262e12Eb5b94a11721dB422Ab51e468Ce1755" },
    "PoolFactory":  { "proxy": "0x08f41dB5B153d07aB21167287F5faA8AB63d4885" },
    "SwapRouter":   { "address": "0x0EF3Db99fD2611637a97193a065362D16167074E" },
    "BondingCurve": { "proxy": "0x1B56D0d77552369FEC1F692f902E2f882dcc84Db" }
  },
  "wiring": {
    "TokenFactory -> FeeRouter": true,
    "TokenFactory -> HookManager": true,
    "Arena -> FeeRouter": true,
    "Events -> FeeRouter": true
  }
}

Proxy pattern

All contracts use the UUPS (Universal Upgradeable Proxy Standard) pattern. The upgrade logic lives in the implementation contract, not the proxy. Only addresses with the UPGRADER_ROLE can authorize upgrades.

// All contracts follow this pattern
contract TokenFactory is
    Initializable,
    AccessControlUpgradeable,
    PausableUpgradeable,
    UUPSUpgradeable
{
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function initialize(address admin) public initializer {
        __AccessControl_init();
        __Pausable_init();
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _grantRole(UPGRADER_ROLE, admin);
    }

    function _authorizeUpgrade(address)
        internal override onlyRole(UPGRADER_ROLE) {}
}

Access control

Each contract uses OpenZeppelin's AccessControlUpgradeable with the following roles:

Deploying

Use the provided Hardhat deployment script. It deploys all six contracts as proxies and wires them together.

# Clone and install
cd contracts
npm install

# Configure environment
cp .env.example .env
# Edit .env with your RPC URL and deployer key

# Deploy to Sepolia
npx hardhat run scripts/deploy.ts --network sepolia

# Verify on Etherscan
npx hardhat verify --network sepolia <PROXY_ADDRESS>

Upgrading

To upgrade a contract, deploy a new implementation and call upgradeToAndCall() on the proxy. The Hardhat upgrades plugin handles this safely.

import { ethers, upgrades } from "hardhat";

async function main() {
  const TokenFactoryV2 = await ethers.getContractFactory(
    "TokenFactoryV2"
  );

  const proxy = await upgrades.upgradeProxy(
    "0xProxyAddress...",
    TokenFactoryV2
  );

  console.log("Upgraded to:", await proxy.getAddress());
}

main();

ABIs

Contract ABIs are generated during compilation and available in artifacts/contracts/. The SDK bundles all ABIs — you typically do not need to reference them directly.

// ABIs are bundled in the SDK
import {
  TokenFactoryABI,
  HookRegistryABI,
  ArenaABI,
} from "@hookos/sdk/abis";

Fee configuration

All protocol fees flow through the FeeRouter, which distributes them according to configurable shares: 50% treasury, 30% hook authors, 20% LP rewards.

Security

• Reentrancy guards on Arena, Events, and FeeRouter (OpenZeppelin ReentrancyGuard with transient storage)
• Pausable — All contracts can be paused by admin in emergencies
• UUPS upgrade authorization restricted to UPGRADER_ROLE
• Constructor initializer disabled to prevent implementation contract hijacking
• Role-based access control with granular permissions per contract
• Gas limits on hook execution (default 500,000) to prevent griefing attacks
• Max hooks per token capped at 8 to bound execution cost
• Wager limits — min/max wager enforcement on Arena battles

Test coverage

The contract suite includes 197 tests covering initialization, happy paths, access control, revert cases, event emissions, and full lifecycle flows for all 6 contracts. Run them with:

cd contracts
npx hardhat test

Monitoring and notifications

Stay up to date with contract activity through the HookOS bots:

• Telegram deploys channel — @hookosdeploys — real-time rich deploy notifications with contract addresses, gas costs, and explorer links
• Discord Bot — Add to your server — slash commands for protocol stats and deploy alerts
• HookAlpha Bot — @HookAlphaBot — interactive charts, token analytics, and protocol dashboard
• Admin dashboard — admin.hookos.fun — wallet-gated admin panel for hook moderation, pause/unpause, and fee configuration