Skip to content

README.md

Latest commit

 

History

History
408 lines (309 loc) · 10.4 KB

README.md

File metadata and controls

408 lines (309 loc) · 10.4 KB

ATOS Token — ERC-20 Smart Contract

Solidity Hardhat OpenZeppelin Network License

📌 Overview

ATOS Token is a production-ready, audit-standard ERC-20 token built with OpenZeppelin contracts. It is the foundational smart contract layer of the Autonomous Token Orchestration System (ATOS) — a decentralized multi-agent platform built on libp2p principles.

Part of NSUT x SEETA x AIC initiative.

✨ Features

Feature Description
✅ ERC-20 Standard Fully compliant ERC-20 token
✅ Mintable Role-based minting
✅ Burnable Token burning (user + admin)
✅ Capped Max supply of 2,000,000 ATOS
✅ Pausable Emergency pause/unpause
✅ ERC20Permit Gasless approvals (EIP-2612)
✅ AccessControl Multi-role permission system
✅ Miner Rewards Auto-reward block miners
✅ Ownable Contract ownership management

📋 Token Details

Property Value
Name ATOS
Symbol ATOS
Decimals 18
Initial Supply 200,000 ATOS
Max Supply (Cap) 2,000,000 ATOS
Network Sepolia Testnet
Standard ERC-20
License MIT

🏗️ Project Structure

ERC20-EXP/
├── contracts/
│   └── ATOSToken.sol          # Main ERC-20 contract
├── ignition/
│   └── modules/
│       └── ATOSToken.ts       # Hardhat Ignition deploy module
├── scripts/
│   └── deploy.ts              # Deploy script (alternative)
├── test/
│   └── ATOSToken.test.ts      # Unit tests
├── hardhat.config.ts          # Hardhat v3 configuration
├── package.json
├── .env.example
└── README.md

🔐 Roles & Access Control

Role Capability
DEFAULT_ADMIN_ROLE Manage all roles
MINTER_ROLE Mint new tokens
BURNER_ROLE Burn tokens from any address
PAUSER_ROLE Pause and unpause transfers

All roles are assigned to the deployer at construction. Roles can be granted or revoked via grantRole / revokeRole.

📄 Smart Contract

// contracts/ATOSToken.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
import {ERC20Capped} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
import {ERC20Pausable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";

contract ATOSToken is
    ERC20,
    Ownable,
    ERC20Burnable,
    ERC20Capped,
    ERC20Pausable,
    ERC20Permit,
    AccessControl
{
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

    // ... (see full contract in contracts/ATOSToken.sol)
}

🚀 Getting Started

Prerequisites

  • Node.js >= 18
  • npm or yarn
  • MetaMask wallet
  • Sepolia testnet ETH

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/ERC20-EXP.git

# Navigate to project
cd ERC20-EXP

# Install dependencies
npm install

Environment Setup

# Set environment variables (Linux/Mac)
export SEPOLIA_RPC_URL="https://sepolia.infura.io/v3/YOUR_KEY"
export SEPOLIA_PRIVATE_KEY="0xYOUR_PRIVATE_KEY"

# Windows (PowerShell)
setx SEPOLIA_RPC_URL "https://sepolia.infura.io/v3/YOUR_KEY"
setx SEPOLIA_PRIVATE_KEY "0xYOUR_PRIVATE_KEY"

⚙️ Hardhat Configuration

// hardhat.config.ts
import hardhatToolboxMochaEthersPlugin from
  "@nomicfoundation/hardhat-toolbox-mocha-ethers";
import { defineConfig } from "hardhat/config";

const SEPOLIA_RPC_URL = process.env.SEPOLIA_RPC_URL ?? "";
const SEPOLIA_PRIVATE_KEY = process.env.SEPOLIA_PRIVATE_KEY ?? "";

export default defineConfig({
  plugins: [hardhatToolboxMochaEthersPlugin],
  solidity: {
    profiles: {
      default: { version: "0.8.28" },
      production: {
        version: "0.8.28",
        settings: {
          optimizer: { enabled: true, runs: 200 },
        },
      },
    },
  },
  networks: {
    sepolia: {
      type: "http",
      chainType: "l1",
      url: SEPOLIA_RPC_URL,
      accounts: SEPOLIA_PRIVATE_KEY ? [SEPOLIA_PRIVATE_KEY] : [],
    },
  },
});

🔨 Compile

# Compile contracts
npx hardhat compile

🚀 Deploy

Using Hardhat Ignition (Recommended)

npx hardhat ignition deploy ignition/modules/ATOSToken.ts \
  --network sepolia

Check Deployed Address

cat ignition/deployments/chain-11155111/deployed_addresses.json

✅ Verify on Etherscan

npx hardhat ignition verify chain-11155111

Or:

npx hardhat verify --network sepolia YOUR_CONTRACT_ADDRESS

🧪 Testing All Functions

Read Functions

Function Expected Output
name() ATOS
symbol() ATOS
decimals() 18
totalSupply() 200000 × 10^18
cap() 2000000 × 10^18
paused() false
owner() deployer address

Write Functions

Function Parameters Result
mint to, amount Mints tokens
burn amount Burns caller's tokens
adminBurn from, amount Burns any address tokens
pauseContract — Pauses all transfers
unpause — Resumes transfers
transfer to, amount Transfers tokens
approve spender, amount Approves allowance
transferFrom from, to, amount Transfers on behalf
grantRole role, account Grants a role
revokeRole role, account Revokes a role

📡 Deployed Contract

Property Value
Network Sepolia Testnet
Contract Address 0xYOUR_DEPLOYED_ADDRESS
Etherscan View on Etherscan
Verified ✅ Yes

🗺️ Roadmap

Phase 1 — ERC-20 Smart Contract        ✅ DONE
Phase 2 — Multi-Agent Framework        🔜 Next
Phase 3 — DEX Integration (Uniswap)    🔜 Planned
Phase 4 — PQC Integration              🔜 Planned
Phase 5 — IPLD + Multiformats          🔜 Planned
Phase 6 — CEX Preparation              🔜 Planned
Phase 7 — Dashboard                    🔜 Planned

🏛️ Architecture Overview

┌─────────────────────────────────────────┐
│         ATOS — Full System              │
├─────────────────────────────────────────┤
│  Smart Contract Layer (✅ Done)         │
│  ┌─────────────────────────────────┐   │
│  │  ATOSToken.sol                  │   │
│  │  ERC20 + Roles + Permit + Cap   │   │
│  └─────────────────────────────────┘   │
├─────────────────────────────────────────┤
│  Multi-Agent Layer (🔜 Next)           │
│  ┌──────┐ ┌──────┐ ┌──────┐           │
│  │Deploy│ │ Liq  │ │ Mon  │           │
│  │Agent │ │Agent │ │Agent │           │
│  └──────┘ └──────┘ └──────┘           │
├─────────────────────────────────────────┤
│  libp2p Network Layer                   │
│  Peer Discovery + PubSub + Transport    │
├─────────────────────────────────────────┤
│  DEX Layer (Uniswap V3)                │
│  Liquidity Pools + Swaps               │
├─────────────────────────────────────────┤
│  Data Layer (IPLD + Multiformats)      │
│  Agent State + Task DAGs + Logs        │
└─────────────────────────────────────────┘

🛠️ Tech Stack

Technology Purpose
Solidity 0.8.28 Smart contract language
Hardhat v3 Development environment
OpenZeppelin 5.x Secure contract libraries
Hardhat Ignition Deployment system
TypeScript Scripting + config
Ethers.js Blockchain interaction
Sepolia Test network

👥 Team

Role Organization
Developer NSUT
Mentor @seetadev
Mentor @johannamoran
Mentor @aspiringsecurity
Mentor @yashksaini-coder
Mentor @prithagupta
Mentor @acul71

🤝 Contributing

  1. Fork the repository
  2. Create your feature branch
git checkout -b feature/your-feature
  1. Commit your changes
git commit -m "Add: your feature"
  1. Push to the branch
git push origin feature/your-feature
  1. Open a Pull Request

🔒 Security

  • All roles use OpenZeppelin AccessControl
  • Contract is pausable in case of emergency
  • Cap prevents infinite minting
  • Never share your private key
  • Use hardware wallet for mainnet

📜 License

This project is licensed under the MIT License.

🔗 Links

Built with ❤️ by NSUT x SEETA x AIC