aitbc/packages/solidity/aitbc-token/docs/DEPLOYMENT.md

AIToken Deployment Guide

This guide covers deploying the AIToken and AITokenRegistry contracts.

Prerequisites

• Node.js 18+
• Hardhat
• Private key with ETH for gas
• RPC endpoint for target network

Contracts

Contract	Description
AIToken.sol	ERC20 token with receipt-based minting
AITokenRegistry.sol	Provider registration and collateral tracking

Environment Setup

Create .env file:

# Required
PRIVATE_KEY=0x...your_deployer_private_key

# Network RPC endpoints
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY

# Optional: Role assignments during deployment
COORDINATOR_ADDRESS=0x...coordinator_address
ATTESTOR_ADDRESS=0x...attestor_address

# Etherscan verification
ETHERSCAN_API_KEY=your_api_key

Network Configuration

Update hardhat.config.ts:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
import * as dotenv from "dotenv";

dotenv.config();

const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    sepolia: {
      url: process.env.SEPOLIA_RPC_URL || "",
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
    mainnet: {
      url: process.env.MAINNET_RPC_URL || "",
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
  },
  etherscan: {
    apiKey: process.env.ETHERSCAN_API_KEY,
  },
};

export default config;

Deployment Steps

1. Compile Contracts

npx hardhat compile

2. Run Tests

npx hardhat test

3. Deploy to Testnet (Sepolia)

# Set environment
export COORDINATOR_ADDRESS=0x...
export ATTESTOR_ADDRESS=0x...

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

Expected output:

Deploying AIToken using admin: 0x...
AIToken deployed to: 0x...
Granting coordinator role to 0x...
Granting attestor role to 0x...
Deployment complete. Export AITOKEN_ADDRESS= 0x...

4. Verify on Etherscan

npx hardhat verify --network sepolia DEPLOYED_ADDRESS "ADMIN_ADDRESS"

5. Deploy Registry (Optional)

npx hardhat run scripts/deploy-registry.ts --network sepolia

Post-Deployment

Grant Additional Roles

// In Hardhat console
const token = await ethers.getContractAt("AIToken", "DEPLOYED_ADDRESS");
const coordinatorRole = await token.COORDINATOR_ROLE();
await token.grantRole(coordinatorRole, "NEW_COORDINATOR_ADDRESS");

Test Minting

npx hardhat run scripts/mintWithReceipt.ts --network sepolia

Mainnet Deployment Checklist

• All tests passing
• Security audit completed
• Testnet deployment verified
• Gas estimation reviewed
• Multi-sig wallet for admin role
• Role addresses confirmed
• Deployment script reviewed
• Emergency procedures documented

Gas Estimates

Operation	Estimated Gas
Deploy AIToken	~1,500,000
Deploy Registry	~800,000
Grant Role	~50,000
Mint with Receipt	~80,000
Register Provider	~60,000

Security Considerations

1. Admin Key Security: Use hardware wallet or multi-sig for admin
2. Role Management: Carefully manage COORDINATOR and ATTESTOR roles
3. Receipt Replay: Contract prevents receipt reuse via consumedReceipts mapping
4. Signature Verification: Uses OpenZeppelin ECDSA for secure signature recovery

Troubleshooting

"invalid attestor signature"

• Verify attestor has ATTESTOR_ROLE
• Check signature was created with correct chain ID and contract address
• Ensure message hash matches expected format

"receipt already consumed"

• Each receipt hash can only be used once
• Generate new unique receipt hash for each mint

"AccessControl: account ... is missing role"

• Grant required role to the calling address
• Verify role was granted on correct contract instance

Contract Addresses

Testnet (Sepolia)

Contract	Address
AIToken	TBD
AITokenRegistry	TBD

Mainnet

Contract	Address
AIToken	TBD
AITokenRegistry	TBD