hanzo-contracts

Hanzo Contracts is the smart contract repository for the Hanzo AI ecosystem.

Hanzo Contracts - AI Infrastructure Smart Contracts

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-evm.md, hanzo/hanzo-web3.md

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

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

Quick reference

| Item | Value | |------|-------| | Framework | Foundry | | Solidity | 0.8.31 | | EVM target | Cancun | | Repo | github.com/hanzoai/contracts | | Branch | main | | Build | forge build | | Test | forge test | | Format | forge fmt | | Optimizer | 200 runs, via-IR | | License | MIT |

Contracts

| Contract | Path | Purpose | |----------|------|---------| | AIToken | src/AIToken.sol | ERC20 governance token with staking, vesting, and deflationary burn | | AIFaucet | src/AIFaucet.sol | Token distribution / faucet mechanism | | HanzoRegistry | src/identity-registry/HanzoRegistry.sol | On-chain identity registry |

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/v1/chain/.../rpc"
hanzo_testnet = "http://127.0.0.1:19640/v1/chain/.../rpc"
hanzo_devnet = "http://127.0.0.1:19650/v1/chain/.../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:

| Contract | Solidity | Framework | |----------|----------|-----------| | Proxy.sol | >=0.4.25 <0.6.0 | Truffle | | Versioned.sol | >=0.4.25 <0.6.0 | Truffle | | Blacklist.sol | >=0.4.25 <0.6.0 | Truffle | | Whitelist.sol | >=0.4.25 <0.6.0 | Truffle | | Migrations.sol | >=0.4.25 <0.6.0 | Truffle |

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

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: solidity, foundry, erc20, staking, vesting, luxfi Prerequisites: Foundry, Solidity basics