create-kozalak-l1 0.1.0

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

@@ -0,0 +1,354 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {Test} from "forge-std/Test.sol";
+import {KozaGasToken} from "../src/KozaGasToken.sol";
+import {IERC20Errors} from "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {ERC20Capped} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol";
+
+/**
+ * @title ERC20GasTest
+ * @notice Unit + fuzz tests for KozaGasToken (Phase 1, Template 1).
+ * @dev Foundry test suite covering constructor, mint, burn, ERC-20 transfer, permit, ownership.
+ *      Invariant tests are in ERC20Gas.invariants.t.sol.
+ */
+contract ERC20GasTest is Test {
+    /*//////////////////////////////////////////////////////////////
+                                 STATE
+    //////////////////////////////////////////////////////////////*/
+
+    KozaGasToken internal token;
+
+    address internal owner;
+    uint256 internal ownerKey;
+    address internal alice;
+    uint256 internal aliceKey;
+    address internal bob;
+    address internal charlie;
+
+    string internal constant NAME = "Koza Gas Token";
+    string internal constant SYMBOL = "KGAS";
+    uint256 internal constant CAP = 1_000_000 ether;
+    uint256 internal constant INITIAL_MINT = 100_000 ether;
+
+    /*//////////////////////////////////////////////////////////////
+                                 SETUP
+    //////////////////////////////////////////////////////////////*/
+
+    function setUp() public {
+        (owner, ownerKey) = makeAddrAndKey("owner");
+        (alice, aliceKey) = makeAddrAndKey("alice");
+        bob = makeAddr("bob");
+        charlie = makeAddr("charlie");
+
+        token = new KozaGasToken(NAME, SYMBOL, CAP, INITIAL_MINT, owner);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                              CONSTRUCTOR
+    //////////////////////////////////////////////////////////////*/
+
+    function test_Constructor_SetsMetadata() public view {
+        assertEq(token.name(), NAME);
+        assertEq(token.symbol(), SYMBOL);
+        assertEq(token.decimals(), 18);
+        assertEq(token.cap(), CAP);
+        assertEq(token.totalSupply(), INITIAL_MINT);
+        assertEq(token.balanceOf(owner), INITIAL_MINT);
+        assertEq(token.owner(), owner);
+        assertEq(token.pendingOwner(), address(0));
+    }
+
+    function test_Constructor_DeploysWithoutInitialMint() public {
+        KozaGasToken t = new KozaGasToken(NAME, SYMBOL, CAP, 0, owner);
+        assertEq(t.totalSupply(), 0);
+        assertEq(t.balanceOf(owner), 0);
+    }
+
+    function test_RevertWhen_ConstructorOwnerIsZero() public {
+        // Ownable parent rejects zero address before our body executes
+        vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableInvalidOwner.selector, address(0)));
+        new KozaGasToken(NAME, SYMBOL, CAP, INITIAL_MINT, address(0));
+    }
+
+    function test_RevertWhen_ConstructorCapIsZero() public {
+        // ERC20Capped parent rejects zero cap before our body executes
+        vm.expectRevert(abi.encodeWithSelector(ERC20Capped.ERC20InvalidCap.selector, 0));
+        new KozaGasToken(NAME, SYMBOL, 0, 0, owner);
+    }
+
+    function test_RevertWhen_InitialMintExceedsCap() public {
+        uint256 tooMuch = CAP + 1;
+        vm.expectRevert(abi.encodeWithSelector(KozaGasToken.InitialMintExceedsCap.selector, CAP, tooMuch));
+        new KozaGasToken(NAME, SYMBOL, CAP, tooMuch, owner);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                                 MINT
+    //////////////////////////////////////////////////////////////*/
+
+    function test_Mint_OwnerCanMint() public {
+        uint256 amount = 50_000 ether;
+        vm.prank(owner);
+        token.mint(alice, amount);
+
+        assertEq(token.balanceOf(alice), amount);
+        assertEq(token.totalSupply(), INITIAL_MINT + amount);
+    }
+
+    function test_RevertWhen_NonOwnerMints() public {
+        vm.prank(alice);
+        vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, alice));
+        token.mint(alice, 1 ether);
+    }
+
+    function test_RevertWhen_MintToZeroAddress() public {
+        // ERC20 _mint rejects zero address with ERC20InvalidReceiver
+        vm.prank(owner);
+        vm.expectRevert(abi.encodeWithSelector(IERC20Errors.ERC20InvalidReceiver.selector, address(0)));
+        token.mint(address(0), 1 ether);
+    }
+
+    function test_RevertWhen_MintZeroAmount() public {
+        vm.prank(owner);
+        vm.expectRevert(KozaGasToken.ZeroAmount.selector);
+        token.mint(alice, 0);
+    }
+
+    function test_RevertWhen_MintExceedsCap() public {
+        uint256 remaining = CAP - INITIAL_MINT;
+        uint256 tooMuch = remaining + 1;
+
+        vm.prank(owner);
+        vm.expectRevert(abi.encodeWithSelector(ERC20Capped.ERC20ExceededCap.selector, INITIAL_MINT + tooMuch, CAP));
+        token.mint(alice, tooMuch);
+    }
+
+    function test_Mint_AtExactCapBoundary() public {
+        uint256 remaining = CAP - INITIAL_MINT;
+        vm.prank(owner);
+        token.mint(alice, remaining);
+
+        assertEq(token.totalSupply(), CAP);
+        assertEq(token.balanceOf(alice), remaining);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                                 BURN
+    //////////////////////////////////////////////////////////////*/
+
+    function test_Burn_HolderCanBurnOwnTokens() public {
+        uint256 burnAmount = 10_000 ether;
+
+        vm.prank(owner);
+        token.burn(burnAmount);
+
+        assertEq(token.balanceOf(owner), INITIAL_MINT - burnAmount);
+        assertEq(token.totalSupply(), INITIAL_MINT - burnAmount);
+    }
+
+    function test_RevertWhen_BurnZeroAmount() public {
+        vm.prank(owner);
+        vm.expectRevert(KozaGasToken.ZeroAmount.selector);
+        token.burn(0);
+    }
+
+    function test_RevertWhen_BurnExceedsBalance() public {
+        vm.prank(alice);
+        vm.expectRevert(abi.encodeWithSelector(IERC20Errors.ERC20InsufficientBalance.selector, alice, 0, 1 ether));
+        token.burn(1 ether);
+    }
+
+    function test_Burn_FreesCapHeadroom() public {
+        // owner burns half, then mints back same amount → still under cap
+        uint256 half = INITIAL_MINT / 2;
+
+        vm.prank(owner);
+        token.burn(half);
+
+        vm.prank(owner);
+        token.mint(alice, half);
+
+        assertEq(token.totalSupply(), INITIAL_MINT);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            ERC-20 STANDARD
+    //////////////////////////////////////////////////////////////*/
+
+    function test_Transfer_Standard() public {
+        vm.prank(owner);
+        bool ok = token.transfer(alice, 1000 ether);
+
+        assertTrue(ok);
+        assertEq(token.balanceOf(alice), 1000 ether);
+        assertEq(token.balanceOf(owner), INITIAL_MINT - 1000 ether);
+    }
+
+    function test_Approve_AndTransferFrom() public {
+        vm.prank(owner);
+        token.approve(alice, 500 ether);
+
+        assertEq(token.allowance(owner, alice), 500 ether);
+
+        vm.prank(alice);
+        bool ok = token.transferFrom(owner, bob, 500 ether);
+
+        assertTrue(ok);
+        assertEq(token.balanceOf(bob), 500 ether);
+        assertEq(token.allowance(owner, alice), 0);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                          ERC-2612 PERMIT
+    //////////////////////////////////////////////////////////////*/
+
+    function test_Permit_ValidSignature() public {
+        uint256 value = 100 ether;
+        uint256 deadline = block.timestamp + 1 hours;
+
+        // Fund alice first
+        vm.prank(owner);
+        token.transfer(alice, 100 ether);
+
+        bytes32 digest = _permitDigest(alice, bob, value, token.nonces(alice), deadline);
+        (uint8 v, bytes32 r, bytes32 s) = vm.sign(aliceKey, digest);
+
+        token.permit(alice, bob, value, deadline, v, r, s);
+
+        assertEq(token.allowance(alice, bob), value);
+        assertEq(token.nonces(alice), 1);
+    }
+
+    function test_RevertWhen_PermitExpired() public {
+        // Move forward so deadline=1 (a stale timestamp) is in the past relative to block.timestamp
+        vm.warp(2 days);
+        uint256 deadline = 1;
+
+        bytes32 digest = _permitDigest(alice, bob, 100 ether, 0, deadline);
+        (uint8 v, bytes32 r, bytes32 s) = vm.sign(aliceKey, digest);
+
+        vm.expectRevert();
+        token.permit(alice, bob, 100 ether, deadline, v, r, s);
+    }
+
+    function test_RevertWhen_PermitReplayed() public {
+        uint256 value = 100 ether;
+        uint256 deadline = block.timestamp + 1 hours;
+
+        bytes32 digest = _permitDigest(alice, bob, value, token.nonces(alice), deadline);
+        (uint8 v, bytes32 r, bytes32 s) = vm.sign(aliceKey, digest);
+
+        token.permit(alice, bob, value, deadline, v, r, s);
+
+        // Replay should fail (nonce was consumed)
+        vm.expectRevert();
+        token.permit(alice, bob, value, deadline, v, r, s);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                            OWNABLE2STEP
+    //////////////////////////////////////////////////////////////*/
+
+    function test_TransferOwnership_TwoStep() public {
+        // Step 1: owner initiates transfer
+        vm.prank(owner);
+        token.transferOwnership(alice);
+
+        assertEq(token.owner(), owner, "owner unchanged before accept");
+        assertEq(token.pendingOwner(), alice, "alice is pending");
+
+        // Step 2: alice accepts
+        vm.prank(alice);
+        token.acceptOwnership();
+
+        assertEq(token.owner(), alice, "alice is now owner");
+        assertEq(token.pendingOwner(), address(0), "pending cleared");
+    }
+
+    function test_RevertWhen_NonPendingAcceptsOwnership() public {
+        vm.prank(owner);
+        token.transferOwnership(alice);
+
+        vm.prank(bob);
+        vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, bob));
+        token.acceptOwnership();
+    }
+
+    function test_TransferOwnership_OldOwnerCanCancel() public {
+        vm.prank(owner);
+        token.transferOwnership(alice);
+
+        // owner overrides with another transfer (pending update)
+        vm.prank(owner);
+        token.transferOwnership(charlie);
+
+        assertEq(token.pendingOwner(), charlie);
+
+        // alice can no longer accept
+        vm.prank(alice);
+        vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, alice));
+        token.acceptOwnership();
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                                FUZZ
+    //////////////////////////////////////////////////////////////*/
+
+    function testFuzz_Transfer(uint256 amount) public {
+        amount = bound(amount, 1, INITIAL_MINT);
+
+        vm.prank(owner);
+        bool ok = token.transfer(alice, amount);
+        assertTrue(ok);
+
+        assertEq(token.balanceOf(alice), amount);
+        assertEq(token.balanceOf(owner), INITIAL_MINT - amount);
+    }
+
+    function testFuzz_MintRespectsCap(uint256 amount) public {
+        // Bound to avoid uint256 overflow on INITIAL_MINT + amount
+        amount = bound(amount, 1, type(uint128).max);
+
+        uint256 remaining = CAP - INITIAL_MINT;
+
+        vm.prank(owner);
+        if (amount > remaining) {
+            vm.expectRevert(abi.encodeWithSelector(ERC20Capped.ERC20ExceededCap.selector, INITIAL_MINT + amount, CAP));
+        }
+        token.mint(alice, amount);
+
+        assertLe(token.totalSupply(), CAP);
+    }
+
+    function testFuzz_BurnDoesNotUnderflow(uint256 amount) public {
+        amount = bound(amount, 1, INITIAL_MINT);
+
+        vm.prank(owner);
+        token.burn(amount);
+
+        assertEq(token.balanceOf(owner), INITIAL_MINT - amount);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                              HELPERS
+    //////////////////////////////////////////////////////////////*/
+
+    function _permitDigest(
+        address ownerAddr,
+        address spender,
+        uint256 value,
+        uint256 nonce,
+        uint256 deadline
+    )
+        internal
+        view
+        returns (bytes32)
+    {
+        bytes32 PERMIT_TYPEHASH =
+            keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)");
+        bytes32 structHash = keccak256(abi.encode(PERMIT_TYPEHASH, ownerAddr, spender, value, nonce, deadline));
+        return keccak256(abi.encodePacked("\x19\x01", token.DOMAIN_SEPARATOR(), structHash));
+    }
+}

package/templates/erc721-collection/.env.example

@@ -0,0 +1,37 @@
+# ============================================
+# Bu dosyayı kopyalayıp `.env` olarak adlandırın. `.env` ASLA commit edilmez.
+# ============================================
+
+# ---- Deploy Wallet (Fuji testnet) ----
+# UYARI: Mainnet private key'i ASLA buraya koyma. Sadece testnet için.
+# Production'da Foundry Cast Wallet (encrypted keystore) veya hardware wallet kullan.
+PRIVATE_KEY=
+
+# Deployer adres (sanity check, opsiyonel)
+DEPLOYER_ADDRESS=
+
+# ---- Block Explorer (Routescan) ----
+# routescan.io'dan ücretsiz `rs_` prefix'li API key al. `--verify` için gerekir.
+SNOWTRACE_API_KEY=
+
+# ---- ICM / Teleporter ----
+# Avalanche Teleporter messenger — tüm L1'lerde deterministic adres.
+TELEPORTER_MESSENGER_ADDRESS=0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf
+
+# ---- ERC-721 Collection parametreleri ----
+# Koleksiyon adı (opsiyonel)
+NFT_NAME=
+# Koleksiyon sembolü (opsiyonel)
+NFT_SYMBOL=
+# Base URI (ipfs://.../ ile bitmeli) (opsiyonel)
+NFT_BASE_URI=
+# Maksimum arz (opsiyonel)
+NFT_MAX_SUPPLY=
+# Mint fiyatı (wei) (opsiyonel)
+NFT_MINT_PRICE=
+# Royalty (basis points, 500 = %5) (opsiyonel)
+NFT_ROYALTY_BPS=
+# Royalty alıcı adresi (opsiyonel)
+NFT_ROYALTY_RECEIVER=
+# Sahip adresi (boş → deployer) (opsiyonel)
+NFT_OWNER=

package/templates/erc721-collection/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "lib/forge-std"]
+	path = lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/openzeppelin-contracts"]
+	path = lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts

package/templates/erc721-collection/README.md

@@ -0,0 +1,48 @@
+# ERC-721 Collection
+
+Merkle allowlist + faz bazlı mint, royalty destekli NFT koleksiyonu (KozaCollection).
+
+Bu, kozalak-l1 deposundan üretilmiş **standalone** bir Foundry projesidir;
+kendi başına derlenir ve test edilir.
+
+## Kurulum
+
+```bash
+forge install foundry-rs/forge-std@8987040ede9553cea20c95ad40d0455930f9c8e0 OpenZeppelin/openzeppelin-contracts@e4f70216d759d8e6a64144a9e1f7bbeed78e7079
+forge build
+forge test
+```
+
+> `forge install ...@<commit>` bağımlılıkları repo ile birebir aynı commit'lere
+> pinler (aşağıdaki tabloya bakın). `.gitmodules` ve `remappings.txt`
+> bu pinlerle uyumludur.
+
+## Deploy (Fuji testnet)
+
+```bash
+cp .env.example .env      # PRIVATE_KEY + SNOWTRACE_API_KEY doldur
+forge script script/DeployERC721Collection.s.sol \
+    --rpc-url fuji \
+    --broadcast \
+    --verify
+```
+
+> Production: `PRIVATE_KEY` yalnızca testnet olmalı; sahiplik/yönetici
+> adreslerini bir multisig'e (Safe) yönlendir, EOA bırakma.
+
+## Yeniden adlandırma
+
+Contract'ı kendi adınla yeniden adlandırmak istersen `src/`, `test/` ve
+`script/` altındaki dosyalarda contract/dosya adını birlikte güncelle
+(import'lar tek-seviye relative olduğu için tutarlı kalmalı).
+
+## Bağımlılık pinleri
+
+| Bağımlılık | Tag | Commit (pin) |
+| --- | --- | --- |
+| `forge-std` | v1.16.0 | `8987040ede9553cea20c95ad40d0455930f9c8e0` |
+| `openzeppelin-contracts` | v5.3.0 | `e4f70216d759d8e6a64144a9e1f7bbeed78e7079` |
+
+---
+
+_Bu proje `create-kozalak-l1` tarafından üretildi. Kaynak: kozalak-l1 mono-repo._

package/templates/erc721-collection/foundry.toml

@@ -0,0 +1,35 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+test = "test"
+script = "script"
+# Bu şablon solc 0.8.34 pragma'sı kullanır. auto_detect_solc dosya
+# pragma'sına göre doğru derleyiciyi otomatik indirir/seçer.
+auto_detect_solc = true
+optimizer = true
+optimizer_runs = 200
+via_ir = true
+bytecode_hash = "none"
+cbor_metadata = false
+remappings = [
+    "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/",
+    "forge-std/=lib/forge-std/src/"
+]
+
+[fmt]
+line_length = 120
+tab_width = 4
+bracket_spacing = false
+int_types = "long"
+multiline_func_header = "all"
+quote_style = "double"
+number_underscore = "thousands"
+
+[rpc_endpoints]
+fuji = "https://api.avax-test.network/ext/bc/C/rpc"
+avalanche = "https://api.avax.network/ext/bc/C/rpc"
+
+[etherscan]
+fuji = { key = "${SNOWTRACE_API_KEY}", url = "https://api.routescan.io/v2/network/testnet/evm/43113/etherscan", chain = 43113 }
+avalanche = { key = "${SNOWTRACE_API_KEY}", url = "https://api.routescan.io/v2/network/mainnet/evm/43114/etherscan", chain = 43114 }

package/templates/erc721-collection/gitignore

@@ -0,0 +1,5 @@
+.env
+out/
+cache/
+broadcast/
+lib/

package/templates/erc721-collection/remappings.txt

@@ -0,0 +1,2 @@
+@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
+forge-std/=lib/forge-std/src/

package/templates/erc721-collection/script/DeployERC721Collection.s.sol

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.34;
+
+import {Script} from "forge-std/Script.sol";
+import {console2} from "forge-std/console2.sol";
+import {KozaCollection} from "../src/KozaCollection.sol";
+
+/**
+ * @title DeployERC721Collection
+ * @notice Foundry deployment script for KozaCollection (Phase 1, Template 2).
+ *
+ *         Usage (Fuji testnet, with .env populated):
+ *
+ *             forge script script/deploy/DeployERC721Collection.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):
+ *           - NFT_NAME                  ("Koza Genesis")
+ *           - NFT_SYMBOL                ("KOZA")
+ *           - NFT_BASE_URI              ("ipfs://CHANGE_ME/")  — sonu `/` ile bitir
+ *           - NFT_MAX_SUPPLY            (5000)
+ *           - NFT_MINT_PRICE            (0.05 ether)
+ *           - NFT_ROYALTY_RECEIVER      (broadcaster)
+ *           - NFT_ROYALTY_BPS           (500 = %5)
+ *           - NFT_OWNER                 (broadcaster)         — production: multisig
+ *
+ *         Production checklist:
+ *           - PRIVATE_KEY testnet-only veya cast-wallet/keystore ile değiştirilmeli
+ *           - NFT_OWNER + NFT_ROYALTY_RECEIVER birer Safe (Gnosis) multisig olmalı
+ *           - NFT_BASE_URI gerçek IPFS CID veya HTTPS gateway içermeli (sonu `/` ile)
+ *           - Snowtrace/Routescan API key `.env`'de SNOWTRACE_API_KEY olarak set'li olmalı
+ */
+contract DeployERC721Collection is Script {
+    /*//////////////////////////////////////////////////////////////
+                                DEFAULTS
+    //////////////////////////////////////////////////////////////*/
+
+    string internal constant DEFAULT_NAME = "Koza Genesis";
+    string internal constant DEFAULT_SYMBOL = "KOZA";
+    string internal constant DEFAULT_BASE_URI = "ipfs://CHANGE_ME/";
+    uint256 internal constant DEFAULT_MAX_SUPPLY = 5000;
+    uint256 internal constant DEFAULT_MINT_PRICE = 0.05 ether;
+    uint96 internal constant DEFAULT_ROYALTY_BPS = 500; // %5
+
+    /*//////////////////////////////////////////////////////////////
+                                  RUN
+    //////////////////////////////////////////////////////////////*/
+
+    /// @notice Entry point invoked by `forge script`. Reads parameters from env.
+    function run() external returns (KozaCollection nft, address deployer) {
+        string memory name = vm.envOr("NFT_NAME", DEFAULT_NAME);
+        string memory symbol = vm.envOr("NFT_SYMBOL", DEFAULT_SYMBOL);
+        string memory baseURI = vm.envOr("NFT_BASE_URI", DEFAULT_BASE_URI);
+        uint256 maxSupply = vm.envOr("NFT_MAX_SUPPLY", DEFAULT_MAX_SUPPLY);
+        uint256 mintPrice = vm.envOr("NFT_MINT_PRICE", DEFAULT_MINT_PRICE);
+        uint256 royaltyBpsRaw = vm.envOr("NFT_ROYALTY_BPS", uint256(DEFAULT_ROYALTY_BPS));
+        uint96 royaltyBps = uint96(royaltyBpsRaw);
+
+        address broadcaster = _resolveBroadcaster();
+        address royaltyReceiver = vm.envOr("NFT_ROYALTY_RECEIVER", broadcaster);
+        address owner = vm.envOr("NFT_OWNER", broadcaster);
+
+        return deploy(name, symbol, baseURI, maxSupply, mintPrice, royaltyReceiver, royaltyBps, 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,
+        string memory baseURI,
+        uint256 maxSupply,
+        uint256 mintPrice,
+        address royaltyReceiver,
+        uint96 royaltyBps,
+        address owner,
+        address broadcaster
+    )
+        public
+        returns (KozaCollection nft, address deployer)
+    {
+        _logPreDeploy(name, symbol, baseURI, maxSupply, mintPrice, royaltyReceiver, royaltyBps, owner, broadcaster);
+
+        vm.startBroadcast();
+        nft = new KozaCollection(name, symbol, baseURI, maxSupply, mintPrice, royaltyReceiver, royaltyBps, owner);
+        vm.stopBroadcast();
+
+        deployer = broadcaster;
+
+        _logPostDeploy(nft, owner);
+    }
+
+    /*//////////////////////////////////////////////////////////////
+                              INTERNALS
+    //////////////////////////////////////////////////////////////*/
+
+    /// @dev Order: explicit DEPLOYER_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,
+        string memory baseURI,
+        uint256 maxSupply,
+        uint256 mintPrice,
+        address royaltyReceiver,
+        uint96 royaltyBps,
+        address owner,
+        address broadcaster
+    )
+        internal
+        pure
+    {
+        console2.log("=== Deploying KozaCollection ===");
+        console2.log("  Broadcaster:    ", broadcaster);
+        console2.log("  Owner:          ", owner);
+        console2.log("  Name:           ", name);
+        console2.log("  Symbol:         ", symbol);
+        console2.log("  Base URI:       ", baseURI);
+        console2.log("  Max supply:     ", maxSupply);
+        console2.log("  Mint price (wei):", mintPrice);
+        console2.log("  Royalty BPS:    ", royaltyBps);
+        console2.log("  Royalty receiver:", royaltyReceiver);
+    }
+
+    function _logPostDeploy(KozaCollection nft, address owner_) internal view {
+        console2.log("=== Deployed ===");
+        console2.log("  Address:        ", address(nft));
+        console2.log("  Owner:          ", nft.owner());
+        console2.log("  Owner (input):  ", owner_);
+        console2.log("  Phase:          ", uint8(nft.phase()));
+        console2.log("");
+        console2.log("Next steps:");
+        console2.log("  1) cast send <addr> 'setMerkleRoot(bytes32)' <root> --rpc-url fuji ...");
+        console2.log("  2) cast send <addr> 'setPhase(uint8)' 1  # Allowlist");
+        console2.log("  3) cast send <addr> 'setPhase(uint8)' 2  # Public");
+    }
+}