Hanzo Contracts - AI Infrastructure Smart Contracts

Overview

Hanzo Contracts is the smart contract repository for the Hanzo AI ecosystem. Built with Foundry and Solidity 0.8.31, it contains three core contracts for the AI token economy, faucet distribution, and on-chain identity registry.

The contracts use @luxfi/ imports (from the Lux standard library) and OpenZeppelin for ERC20, access control, and utility patterns. The repo targets the Cancun EVM version with via-IR compilation and optimizer enabled.

Note: The master branch contains legacy Truffle-era contracts (Proxy, Versioned, Blacklist, Whitelist, Migrations with Solidity <0.6.0). The active main branch is the current Foundry-based codebase documented here.

When to use

• Deploying or interacting with the $AI governance token
• Setting up token vesting schedules or staking
• Distributing tokens via the faucet mechanism
• Managing on-chain identity via HanzoRegistry
• Understanding the Hanzo AI token economics

Hard requirements

1. Foundry (forge, cast, anvil)
2. Solidity 0.8.31 compiler
3. Git submodules for dependencies (@luxfi/standard, forge-std)

Quick reference

Contracts

Project structure

contracts/          (main branch)
├── foundry.toml    # Foundry config (solc 0.8.31, Cancun, via-IR)
├── foundry.lock
├── package.json
├── src/
│   ├── AIToken.sol
│   ├── AIFaucet.sol
│   └── identity-registry/
│       └── HanzoRegistry.sol
├── scripts/        # Deployment scripts
├── broadcast/      # Deployment artifacts
├── lib/            # Git submodule dependencies
│   ├── standard/   # @luxfi/standard (Lux standard library)
│   └── forge-std/  # Foundry test utilities
└── .github/        # CI workflows

AIToken.sol

ERC20 governance token ("AI Token", ticker "AI") with a 1 billion max supply:

• Distribution: 15% team, 35% ecosystem, 20% public sale, 10% liquidity, 20% staking rewards
• Staking: Lock periods of 0/30/90/180/365 days with 1-15% APR reward rates
• Vesting: Per-address vesting schedules with cliff and linear unlock
• Burn: Deflationary 0.1% burn rate on transfers (configurable by owner)
• Pausable: Owner can pause all transfers
• Imports: @luxfi/tokens/LRC20/LRC20.sol, @luxfi/access/Access.sol, @luxfi/utils/Utils.sol

Foundry remappings

remappings = [
    "@luxfi/=lib/standard/contracts/",
    "@luxfi/standard/=lib/standard/contracts/",
    "@openzeppelin/contracts/=lib/standard/lib/openzeppelin-contracts/contracts/",
    "@openzeppelin/contracts-upgradeable/=lib/standard/lib/openzeppelin-contracts-upgradeable/contracts/",
    "forge-std/=lib/forge-std/src/",
]

RPC endpoints (from foundry.toml)

hanzo_mainnet = "http://127.0.0.1:19630/ext/bc/.../rpc"
hanzo_testnet = "http://127.0.0.1:19640/ext/bc/.../rpc"
hanzo_devnet  = "http://127.0.0.1:19650/ext/bc/.../rpc"

These point to local Lux subnet RPC endpoints for development.

Development

git clone https://github.com/hanzoai/contracts.git
cd contracts
git checkout main
git submodule update --init --recursive
forge build
forge test
forge fmt

One-file quickstart

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

import {AIToken} from "src/AIToken.sol";

// Deploy with treasury address
// AIToken token = new AIToken(treasuryAddress);
// token.stake(1000 * 10**18, 90);  // Stake 1000 AI for 90 days at 6% APR

Legacy branch (master)

The master branch is a historical artifact containing the original Hanzo Solidity contracts:

Published as hanzo-solidity v0.2.1 on npm. Uses openzeppelin-solidity v2.1.2. Not used for new development.

Related Skills

• hanzo/hanzo-evm.md - Rust EVM execution engine (reth fork)
• hanzo/hanzo-web3.md - Blockchain API access
• hanzo/hanzo-web3-gateway.md - Keyless blockchain access via x402