create-kozalak-l1 0.1.0

package/templates/erc20-gas/script/DeployERC20Gas.s.sol

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {Script} from "forge-std/Script.sol";
+import {console2} from "forge-std/console2.sol";
+import {KozaGasToken} from "../src/KozaGasToken.sol";
+
+/**
+ * @title DeployERC20Gas
+ * @notice Foundry deployment script for KozaGasToken (Phase 1, Template 1).
+ *
+ *         Usage (Fuji testnet, with .env populated):
+ *
+ *             forge script script/deploy/DeployERC20Gas.s.sol \
+ *                 --rpc-url fuji \
+ *                 --broadcast \
+ *                 --verify
+ *
+ *         Required env (loaded by `forge` from .env):
+ *           - PRIVATE_KEY                — deployer private key (testnet only!)
+ *
+ *         Optional env (defaults below if unset):
+ *           - ERC20_NAME            ("Koza Gas Token")
+ *           - ERC20_SYMBOL          ("KGAS")
+ *           - ERC20_CAP             (1_000_000 ether)   — total supply hard cap
+ *           - ERC20_INITIAL_MINT    (100_000 ether)     — minted to owner at deploy
+ *           - ERC20_OWNER           (msg.sender)        — production: pass a multisig
+ *
+ *         Production checklist:
+ *           - PRIVATE_KEY must be testnet-only OR replaced with cast-wallet/keystore
+ *           - ERC20_OWNER must point to a Safe (Gnosis Safe) multisig, never an EOA
+ *           - SNOWTRACE_API_KEY in .env (set to "verifyContract" for free Routescan tier)
+ */
+contract DeployERC20Gas is Script {
+    /*//////////////////////////////////////////////////////////////
+                                DEFAULTS
+    //////////////////////////////////////////////////////////////*/
+
+    string internal constant DEFAULT_NAME = "Koza Gas Token";
+    string internal constant DEFAULT_SYMBOL = "KGAS";
+    uint256 internal constant DEFAULT_CAP = 1_000_000 ether;
+    uint256 internal constant DEFAULT_INITIAL_MINT = 100_000 ether;
+
+    /*//////////////////////////////////////////////////////////////
+                                  RUN
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Entry point invoked by `forge script`. Reads parameters from env.
+    function run() external returns (KozaGasToken token, address deployer) {
+        string memory name = vm.envOr("ERC20_NAME", DEFAULT_NAME);
+        string memory symbol = vm.envOr("ERC20_SYMBOL", DEFAULT_SYMBOL);
+        uint256 cap = vm.envOr("ERC20_CAP", DEFAULT_CAP);
+        uint256 initialMint = vm.envOr("ERC20_INITIAL_MINT", DEFAULT_INITIAL_MINT);
+
+        address broadcaster = _resolveBroadcaster();
+        address owner = vm.envOr("ERC20_OWNER", broadcaster);
+
+        return deploy(name, symbol, cap, initialMint, owner, broadcaster);
+    }
+
+    /// @notice Test-friendly entry point. Takes explicit parameters instead of env.
+    /// @dev Prefer this from Foundry tests so env state does not leak between cases.
+    function deploy(
+        string memory name,
+        string memory symbol,
+        uint256 cap,
+        uint256 initialMint,
+        address owner,
+        address broadcaster
+    )
+        public
+        returns (KozaGasToken token, address deployer)
+    {
+        _logPreDeploy(name, symbol, cap, initialMint, owner, broadcaster);
+
+        vm.startBroadcast();
+        token = new KozaGasToken(name, symbol, cap, initialMint, owner);
+        vm.stopBroadcast();
+
+        deployer = broadcaster;
+
+        _logPostDeploy(token, owner);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                              INTERNALS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Returns the address that will broadcast txs for this run.
+    ///      Order: explicit DEPLOYER_ADDRESS > address derived from PRIVATE_KEY > tx.origin.
+    function _resolveBroadcaster() internal view returns (address) {
+        address explicitDeployer = vm.envOr("DEPLOYER_ADDRESS", address(0));
+        if (explicitDeployer != address(0)) return explicitDeployer;
+
+        uint256 pk = vm.envOr("PRIVATE_KEY", uint256(0));
+        if (pk != 0) return vm.addr(pk);
+
+        return tx.origin;
+    }
+
+    function _logPreDeploy(
+        string memory name,
+        string memory symbol,
+        uint256 cap,
+        uint256 initialMint,
+        address owner,
+        address broadcaster
+    )
+        internal
+        pure
+    {
+        console2.log("=== Deploying KozaGasToken ===");
+        console2.log("  Broadcaster:    ", broadcaster);
+        console2.log("  Owner:          ", owner);
+        console2.log("  Name:           ", name);
+        console2.log("  Symbol:         ", symbol);
+        console2.log("  Cap (wei):      ", cap);
+        console2.log("  Initial mint:   ", initialMint);
+    }
+
+    function _logPostDeploy(KozaGasToken token, address owner) internal view {
+        console2.log("=== Deployed ===");
+        console2.log("  Address:        ", address(token));
+        console2.log("  Total supply:   ", token.totalSupply());
+        console2.log("  Cap:            ", token.cap());
+        console2.log("  Owner balance:  ", token.balanceOf(owner));
+        console2.log("");
+        console2.log("Verify on Snowtrace:");
+        console2.log("  forge verify-contract <address> KozaGasToken --rpc-url fuji");
+    }
+}

package/templates/erc20-gas/src/KozaGasToken.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {ERC20Capped} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
+import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
+import {Ownable, Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+
+/**
+ * @title KozaGasToken
+ * @author kozalak-L1 contributors
+ * @notice ERC-20 + Capped + Permit + Ownable2Step token. Subnet-EVM L1'de native gas
+ *         token olarak veya C-Chain üzerinde yardımcı token olarak kullanılabilir.
+ * @dev OpenZeppelin v5.3+ pattern'leri ile audit-grade boilerplate. Custom logic minimum.
+ *
+ *      Güvenlik:
+ *      - Ownable2Step: tek-adımlı ownership transfer riski sıfırlanır (yanlış adres koruması)
+ *      - ERC20Capped: total supply hard-cap, sınırsız enflasyon yok
+ *      - ERC20Permit (EIP-2612): gasless approve, smart wallet UX
+ *      - Custom errors: gas + audit kalitesi (require string yerine)
+ *
+ *      Constructor input validation OpenZeppelin parent kontratlarına bırakıldı:
+ *      - cap_ == 0       → ERC20Capped.ERC20InvalidCap(0)
+ *      - initialOwner_ 0 → Ownable.OwnableInvalidOwner(0)
+ *      Bu sayede çift kontrol (gas waste) ve hata mesajı çakışması olmaz.
+ */
+contract KozaGasToken is ERC20Capped, ERC20Permit, Ownable2Step {
+    /*//////////////////////////////////////////////////////////////
+                                ERRORS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Sıfır miktar parametresi geçerli değil (mint, burn için).
+    error ZeroAmount();
+
+    /// @notice Constructor'daki ilk mint cap'i aşıyor.
+    /// @param cap Maksimum total supply
+    /// @param attempted İstenen ilk mint miktarı
+    error InitialMintExceedsCap(uint256 cap, uint256 attempted);
+
+    /*//////////////////////////////////////////////////////////////
+                              CONSTRUCTOR
+    //////////////////////////////////////////////////////////////*/
+
+    /**
+     * @param name_ Token adı (örn. "Koza Gas Token")
+     * @param symbol_ Token sembolü (örn. "KGAS")
+     * @param cap_ Maksimum total supply (wei cinsinden, decimal'i içerir)
+     * @param initialMint_ Constructor'da `initialOwner_`'a mint edilecek miktar (0 olabilir)
+     * @param initialOwner_ Owner adresi (production: multisig, asla EOA değil)
+     */
+    constructor(
+        string memory name_,
+        string memory symbol_,
+        uint256 cap_,
+        uint256 initialMint_,
+        address initialOwner_
+    )
+        ERC20(name_, symbol_)
+        ERC20Capped(cap_)
+        ERC20Permit(name_)
+        Ownable(initialOwner_)
+    {
+        if (initialMint_ > cap_) {
+            revert InitialMintExceedsCap(cap_, initialMint_);
+        }
+
+        if (initialMint_ > 0) {
+            _mint(initialOwner_, initialMint_);
+        }
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            EXTERNAL ACTIONS
+    //////////////////////////////////////////////////////////////*/
+
+    /**
+     * @notice Yeni token mint et. Sadece owner çağırabilir.
+     * @dev Cap kontrolü ERC20Capped tarafından `_update` içinde otomatik yapılır.
+     *      Sıfır adres kontrolü ERC20 `_mint` içinde yapılır (ERC20InvalidReceiver).
+     * @param to Mint edilecek adres
+     * @param amount Mint miktarı (wei cinsinden)
+     */
+    function mint(address to, uint256 amount) external onlyOwner {
+        if (amount == 0) revert ZeroAmount();
+        _mint(to, amount);
+    }
+
+    /**
+     * @notice Çağıran kişi kendi token'larını yakar.
+     * @param amount Yakılacak miktar (wei cinsinden)
+     */
+    function burn(uint256 amount) external {
+        if (amount == 0) revert ZeroAmount();
+        _burn(msg.sender, amount);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                              OVERRIDES
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev ERC20 ve ERC20Capped'in `_update` fonksiyonları çakışıyor; üst sınıfa delegate et.
+    function _update(address from, address to, uint256 value) internal override(ERC20, ERC20Capped) {
+        super._update(from, to, value);
+    }
+}

package/templates/erc20-gas/test/DeployERC20Gas.t.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {Test} from "forge-std/Test.sol";
+import {DeployERC20Gas} from "../script/DeployERC20Gas.s.sol";
+import {KozaGasToken} from "../src/KozaGasToken.sol";
+
+/**
+ * @title DeployERC20GasTest
+ * @notice Smoke tests for the deploy script. Calls `deploy(...)` directly with
+ *         explicit parameters so each test is order-independent and immune to
+ *         leaking env state between Foundry cases.
+ *
+ *         The env-driven `run()` entry point is intentionally not unit-tested here;
+ *         it is exercised via the actual `forge script ... --broadcast` flow on
+ *         Fuji testnet (integration test).
+ */
+contract DeployERC20GasTest is Test {
+    function test_Deploy_WithDefaultParameters() public {
+        DeployERC20Gas deployer = new DeployERC20Gas();
+        address broadcaster = makeAddr("broadcaster");
+
+        (KozaGasToken token, address returnedDeployer) =
+            deployer.deploy("Koza Gas Token", "KGAS", 1_000_000 ether, 100_000 ether, broadcaster, broadcaster);
+
+        assertEq(token.name(), "Koza Gas Token");
+        assertEq(token.symbol(), "KGAS");
+        assertEq(token.cap(), 1_000_000 ether);
+        assertEq(token.totalSupply(), 100_000 ether);
+        assertEq(token.owner(), broadcaster);
+        assertEq(token.balanceOf(broadcaster), 100_000 ether);
+        assertEq(returnedDeployer, broadcaster);
+    }
+
+    function test_Deploy_WithCustomParameters() public {
+        DeployERC20Gas deployer = new DeployERC20Gas();
+        address customOwner = makeAddr("customOwner");
+        address customBroadcaster = makeAddr("customBroadcaster");
+
+        (KozaGasToken token,) =
+            deployer.deploy("Custom Token", "CUST", 2_000_000 ether, 50_000 ether, customOwner, customBroadcaster);
+
+        assertEq(token.name(), "Custom Token");
+        assertEq(token.symbol(), "CUST");
+        assertEq(token.cap(), 2_000_000 ether);
+        assertEq(token.totalSupply(), 50_000 ether);
+        assertEq(token.owner(), customOwner);
+        assertEq(token.balanceOf(customOwner), 50_000 ether);
+    }
+
+    function test_Deploy_NoInitialMint() public {
+        DeployERC20Gas deployer = new DeployERC20Gas();
+        address broadcaster = makeAddr("broadcaster");
+
+        (KozaGasToken token,) = deployer.deploy("Koza Gas Token", "KGAS", 1_000_000 ether, 0, broadcaster, broadcaster);
+
+        assertEq(token.totalSupply(), 0);
+        assertEq(token.balanceOf(broadcaster), 0);
+    }
+}

package/templates/erc20-gas/test/ERC20Gas.invariants.t.sol

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {Test} from "forge-std/Test.sol";
+import {KozaGasToken} from "../src/KozaGasToken.sol";
+
+/**
+ * @title ERC20GasHandler
+ * @notice Foundry invariant testing handler. Bounded random calls into KozaGasToken.
+ * @dev Handler pattern (Foundry stateful fuzzing) — invariant'ların ihlal edilmediği
+ *      her tx sırasında doğrulanır. Owner pranking ile yönetim fonksiyonlarına erişim
+ *      sağlanır.
+ */
+contract ERC20GasHandler is Test {
+    KozaGasToken public token;
+    address public owner;
+    address[] public actors;
+
+    // Mevcut tüm transfer/mint/burn aksiyon sayıları (debug için)
+    uint256 public callCount;
+
+    constructor(KozaGasToken _token, address _owner, address[] memory _actors) {
+        token = _token;
+        owner = _owner;
+        actors = _actors;
+    }
+
+    function _pickActor(uint256 seed) internal view returns (address) {
+        return actors[seed % actors.length];
+    }
+
+    /// @notice Bounded random transfer between actors.
+    function transfer(uint256 fromSeed, uint256 toSeed, uint256 amount) external {
+        callCount++;
+        address from = _pickActor(fromSeed);
+        address to = _pickActor(toSeed);
+
+        uint256 fromBalance = token.balanceOf(from);
+        if (fromBalance == 0) return;
+
+        amount = bound(amount, 1, fromBalance);
+
+        vm.prank(from);
+        try token.transfer(to, amount) returns (bool) {} catch {}
+    }
+
+    /// @notice Bounded random mint by owner.
+    function mint(uint256 toSeed, uint256 amount) external {
+        callCount++;
+        address to = _pickActor(toSeed);
+
+        uint256 cap = token.cap();
+        uint256 totalSupply = token.totalSupply();
+        if (totalSupply >= cap) return;
+
+        // Avoid uint256 overflow by capping at type(uint128).max
+        amount = bound(amount, 1, cap - totalSupply);
+
+        vm.prank(owner);
+        try token.mint(to, amount) {} catch {}
+    }
+
+    /// @notice Bounded random burn by an actor.
+    function burn(uint256 actorSeed, uint256 amount) external {
+        callCount++;
+        address actor = _pickActor(actorSeed);
+
+        uint256 balance = token.balanceOf(actor);
+        if (balance == 0) return;
+
+        amount = bound(amount, 1, balance);
+
+        vm.prank(actor);
+        try token.burn(amount) {} catch {}
+    }
+
+    /// @notice Returns the current actor list (used by invariant test).
+    function getActors() external view returns (address[] memory) {
+        return actors;
+    }
+}
+
+/**
+ * @title ERC20GasInvariantTest
+ * @notice Stateful fuzzing invariants for KozaGasToken. Foundry's invariant runner
+ *         randomly calls handler functions and asserts these invariants hold after
+ *         every call.
+ *
+ *         Tested invariants:
+ *         1. totalSupply() <= cap()        — never exceeds the cap
+ *         2. sum(balanceOf(actors)) == totalSupply()  — balance accounting consistent
+ */
+contract ERC20GasInvariantTest is Test {
+    KozaGasToken internal token;
+    ERC20GasHandler internal handler;
+    address internal owner;
+    address[] internal actors;
+
+    uint256 internal constant CAP = 10_000_000 ether;
+    uint256 internal constant INITIAL_MINT = 1_000_000 ether;
+
+    function setUp() public {
+        owner = makeAddr("owner");
+
+        // Set up 5 actors and seed first one with the initial mint
+        actors.push(owner);
+        actors.push(makeAddr("alice"));
+        actors.push(makeAddr("bob"));
+        actors.push(makeAddr("charlie"));
+        actors.push(makeAddr("dave"));
+
+        token = new KozaGasToken("Koza Gas Token", "KGAS", CAP, INITIAL_MINT, owner);
+        handler = new ERC20GasHandler(token, owner, actors);
+
+        // Configure Foundry invariant runner to only call our handler
+        targetContract(address(handler));
+
+        // Restrict the function selectors that can be invoked
+        bytes4[] memory selectors = new bytes4[](3);
+        selectors[0] = handler.transfer.selector;
+        selectors[1] = handler.mint.selector;
+        selectors[2] = handler.burn.selector;
+        targetSelector(FuzzSelector({addr: address(handler), selectors: selectors}));
+    }
+
+    /// @notice totalSupply must never exceed cap.
+    function invariant_TotalSupplyDoesNotExceedCap() public view {
+        assertLe(token.totalSupply(), token.cap(), "totalSupply > cap");
+    }
+
+    /// @notice Sum of balances across all actors must equal totalSupply.
+    function invariant_SumOfBalancesEqualsTotalSupply() public view {
+        uint256 sum;
+        for (uint256 i = 0; i < actors.length; i++) {
+            sum += token.balanceOf(actors[i]);
+        }
+        assertEq(sum, token.totalSupply(), "sum(balances) != totalSupply");
+    }
+
+    /// @notice Owner remains constant during invariant runs (no ownership change exposed).
+    function invariant_OwnerDoesNotChange() public view {
+        assertEq(token.owner(), owner, "owner mutated unexpectedly");
+    }
+}