# ===== macOS / Linux 설치 스크립트 =====

# 1. nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc  # 또는 source ~/.zshrc

# 2. Node.js 18 LTS 설치
nvm install 18
nvm use 18
nvm alias default 18
node --version   # v18.x.x 확인

# 3. Foundry 설치 (forge, cast, anvil, chisel)
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge --version  # forge 0.2.x 확인

# 4. Hardhat 글로벌 설치 (선택)
npm install -g hardhat

# ===== Windows (PowerShell) =====
# nvm-windows 다운로드: https://github.com/coreybutler/nvm-windows
nvm install 18.17.0
nvm use 18.17.0

// .vscode/settings.json — 권장 설정
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[solidity]": {
    "editor.defaultFormatter": "NomicFoundation.hardhat-solidity"
  },
  "solidity.compileUsingRemoteVersion": "0.8.20",
  "solidity.formatter": "prettier",
  "files.exclude": {
    "**/node_modules": true,
    "**/.git": true
  }
}

# .env 파일 (절대 깃허브에 올리지 마세요!)
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_API_KEY
POLYGONSCAN_API_KEY=YOUR_POLYGONSCAN_API_KEY
COINMARKETCAP_API_KEY=YOUR_CMC_API_KEY  # Gas Reporter USD 환산

# .gitignore — 반드시 추가
.env
.env.local
node_modules/
artifacts/
cache/
typechain-types/
coverage/

⛔ 절대 하지 말아야 할 것

# Hardhat 프로젝트 초기화
mkdir blockchain-project && cd blockchain-project
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox dotenv
npm install @openzeppelin/contracts

npx hardhat init
# → "Create a JavaScript project" 선택

# 최종 프로젝트 구조
blockchain-project/
├── contracts/                 # Solidity 소스
│   ├── Token.sol
│   ├── NFT.sol
│   └── interfaces/
│       └── IToken.sol
├── scripts/                   # 배포/상호작용 스크립트
│   ├── deploy.js
│   └── interact.js
├── test/                      # 테스트 파일
│   ├── Token.test.js
│   └── NFT.test.js
├── ignition/                  # Hardhat Ignition 모듈
│   └── modules/
│       └── Token.js
├── hardhat.config.js          # 핵심 설정 파일
├── .env                       # 환경변수 (gitignore)
├── .gitignore
└── package.json

require("@nomicfoundation/hardhat-toolbox");
require("@openzeppelin/hardhat-upgrades");  // 업그레이더블
require("hardhat-gas-reporter");             // Gas 리포트
require("solidity-coverage");               // 코드 커버리지
require("dotenv").config();

const { PRIVATE_KEY, SEPOLIA_RPC_URL, MAINNET_RPC_URL,
        ETHERSCAN_API_KEY, COINMARKETCAP_API_KEY } = process.env;

module.exports = {
  solidity: {
    compilers: [
      {
        version: "0.8.20",
        settings: {
          optimizer: { enabled: true, runs: 200 },
          viaIR: true  // 대형 컨트랙트 컴파일 최적화
        }
      }
    ]
  },
  networks: {
    hardhat: {
      chainId: 31337,
      forking: {                          // 메인넷 포크 (선택)
        url: MAINNET_RPC_URL,
        blockNumber: 19000000
      }
    },
    localhost: { url: "http://127.0.0.1:8545" },
    sepolia: {
      url: SEPOLIA_RPC_URL || "",
      accounts: PRIVATE_KEY ? [PRIVATE_KEY] : [],
      chainId: 11155111,
      gasPrice: "auto"
    },
    polygon: {
      url: "https://polygon-rpc.com",
      accounts: PRIVATE_KEY ? [PRIVATE_KEY] : [],
      chainId: 137
    },
    arbitrum: {
      url: "https://arb1.arbitrum.io/rpc",
      accounts: PRIVATE_KEY ? [PRIVATE_KEY] : [],
      chainId: 42161
    }
  },
  etherscan: {
    apiKey: {
      mainnet:  ETHERSCAN_API_KEY,
      sepolia:  ETHERSCAN_API_KEY,
      polygon:  process.env.POLYGONSCAN_API_KEY,
      arbitrumOne: process.env.ARBISCAN_API_KEY
    }
  },
  gasReporter: {
    enabled:         process.env.REPORT_GAS === "true",
    currency:        "USD",
    coinmarketcap:   COINMARKETCAP_API_KEY,
    outputFile:      "gas-report.txt",
    noColors:        true
  },
  paths: {
    sources:   "./contracts",
    tests:     "./test",
    cache:     "./cache",
    artifacts: "./artifacts"
  },
  mocha: { timeout: 60000 }  // 느린 테스트 타임아웃
};

// test/Token.test.js — 실전 테스트 패턴
const { expect }              = require("chai");
const { ethers, network }     = require("hardhat");
const { loadFixture, time }   = require("@nomicfoundation/hardhat-network-helpers");

// Fixture: 재사용 가능한 초기 상태 스냅샷
async function deployTokenFixture() {
  const [owner, alice, bob, carol] = await ethers.getSigners();
  const Token = await ethers.getContractFactory("BlockToken");
  const token = await Token.deploy(owner.address);
  await token.waitForDeployment();

  // 초기 세팅
  await token.transfer(alice.address, ethers.parseEther("1000"));
  await token.transfer(bob.address,   ethers.parseEther("500"));

  return { token, owner, alice, bob, carol };
}

describe("BlockToken — 완전한 테스트 스위트", function() {

  describe("Deployment", function() {
    it("초기 공급량 확인", async function() {
      const { token, owner } = await loadFixture(deployTokenFixture);
      const total = await token.totalSupply();
      expect(total).to.equal(ethers.parseEther("10000000"));
    });
  });

  describe("Transfers", function() {
    it("정상 전송", async function() {
      const { token, alice, bob } = await loadFixture(deployTokenFixture);
      await token.connect(alice).transfer(bob.address, ethers.parseEther("100"));
      expect(await token.balanceOf(bob.address)).to.equal(ethers.parseEther("600"));
    });

    it("잔액 부족 revert", async function() {
      const { token, carol } = await loadFixture(deployTokenFixture);
      await expect(
        token.connect(carol).transfer(carol.address, 1)
      ).to.be.reverted;
    });
  });

  describe("Time Travel — 시간 조작 테스트", function() {
    it("1년 후 스테이킹 보상 확인", async function() {
      const { token, alice } = await loadFixture(deployTokenFixture);
      // 1년 뒤로 시간 이동
      await time.increase(365 * 24 * 60 * 60);
      // 보상 계산 로직 테스트...
    });
  });

  describe("Impersonation — 임의 주소 사칭 테스트", function() {
    it("고래 지갑 행동 시뮬레이션", async function() {
      const whaleAddress = "0x28C6c06298d514Db089934071355E5743bf21d60";
      await network.provider.request({
        method: "hardhat_impersonateAccount",
        params: [whaleAddress]
      });
      const whale = await ethers.getSigner(whaleAddress);
      // whale 계정으로 트랜잭션 실행...
    });
  });
});

Gas Reporter 출력 예시

REPORT_GAS=true npx hardhat test

·-------------------------------------|----------------------------|-------------|-----------------------------·
|         Solc version: 0.8.20        ·  Optimizer enabled: true  ·  Runs: 200  ·  Block limit: 30000000 gas  │
······································|····························|·············|······························
|  Methods                                                                                                     │
·············|·······················|············|············|·············|·············|···················
|  Contract  ·  Method               ·  Min       ·  Max       ·  Avg        ·  # calls    ·  usd (avg)       │
·············|·······················|············|············|·············|·············|···················
|  BlockToken·  approve              ·     46,213 ·     46,225 ·     46,221  ·          8  ·          $0.14   │
|  BlockToken·  transfer             ·     51,452 ·     68,652 ·     60,052  ·         15  ·          $0.18   │
|  BlockToken·  mint                 ·     68,924 ·     68,924 ·     68,924  ·          3  ·          $0.21   │
·············|·······················|············|············|·············|·············|···················
|  Deployments                        ·                                       ·  % of limit ·                  │
······································|············|············|·············|·············|···················
|  BlockToken                         ·          - ·          - ·    1,234,567·      4.1 %  ·          $3.71   │
·-------------------------------------|------------|------------|-------------|-------------|-------------------·

# ===== Foundry 프로젝트 세팅 =====
forge init my-foundry-project
cd my-foundry-project

# OpenZeppelin 라이브러리 추가 (forge install)
forge install OpenZeppelin/openzeppelin-contracts
forge install foundry-rs/forge-std

# foundry.toml 설정
[profile.default]
src     = "src"
out     = "out"
libs    = ["lib"]
solc    = "0.8.20"
optimizer       = true
optimizer-runs  = 200
fuzz.runs       = 1000     # Fuzz 테스트 횟수
invariant.runs  = 256

# 빌드 / 테스트 / 가스 스냅샷
forge build
forge test -vvvv           # -v 많을수록 상세 로그
forge snapshot             # gas snapshot 저장
forge coverage             # 커버리지 리포트

// test/Token.t.sol — Foundry 테스트는 Solidity로 작성!
pragma solidity ^0.8.20;

import "forge-std/Test.sol";
import "../src/BlockToken.sol";

contract BlockTokenTest is Test {
    BlockToken public token;
    address public owner   = address(1);
    address public alice   = address(2);
    address public bob     = address(3);

    function setUp() public {
        vm.startPrank(owner);         // owner로 tx 발생
        token = new BlockToken(owner);
        token.transfer(alice, 1000 ether);
        vm.stopPrank();
    }

    // === 기본 테스트 ===
    function test_Transfer() public {
        vm.prank(alice);
        token.transfer(bob, 100 ether);
        assertEq(token.balanceOf(bob), 100 ether);
    }

    function test_RevertWhen_InsufficientBalance() public {
        vm.prank(bob);
        vm.expectRevert();            // revert 예상
        token.transfer(alice, 1);
    }

    // === Fuzz 테스트 — 자동으로 랜덤 입력값 생성! ===
    function testFuzz_Transfer(uint256 amount) public {
        amount = bound(amount, 1, 1000 ether);  // 범위 제한
        vm.prank(alice);
        token.transfer(bob, amount);
        assertEq(token.balanceOf(bob), amount);
        assertEq(token.balanceOf(alice), 1000 ether - amount);
    }

    // === Invariant 테스트 — 불변식 검증 ===
    function invariant_TotalSupplyConstant() public view {
        // 어떤 트랜잭션 후에도 totalSupply는 변하지 않아야 함
        assertEq(token.totalSupply(), 10_000_000 ether);
    }

    // === 시간 조작 ===
    function test_TimeWarp() public {
        uint256 future = block.timestamp + 365 days;
        vm.warp(future);              // 블록 타임스탬프 변경
        vm.roll(block.number + 1000); // 블록 번호 변경
    }

    // === ETH 잔액 설정 ===
    function test_EthBalance() public {
        vm.deal(alice, 10 ether);      // alice에게 ETH 10 부여
        assertEq(alice.balance, 10 ether);
    }
}

# ===== anvil: 로컬 EVM 노드 (Hardhat Node 대체) =====
anvil                        # 기본 실행 (20개 테스트 계정)
anvil --fork-url $MAINNET_RPC_URL --fork-block-number 19000000
anvil --chain-id 1337 --block-time 2  # 2초마다 블록 생성

# ===== cast: 터미널에서 RPC 호출 =====

# 잔액 조회
cast balance 0x742d35Cc6634C0532925a3b8D4C9b5c8b4a6F9F4 --rpc-url $SEPOLIA_RPC_URL

# 컨트랙트 함수 호출 (읽기)
cast call 0xContractAddress "balanceOf(address)(uint256)" 0xAddress --rpc-url $SEPOLIA_RPC_URL

# 컨트랙트 함수 호출 (쓰기 — 트랜잭션)
cast send 0xContractAddress "transfer(address,uint256)" 0xToAddress 1000000000000000000   --private-key $PRIVATE_KEY --rpc-url $SEPOLIA_RPC_URL

# ABI 인코딩/디코딩
cast abi-encode "transfer(address,uint256)" 0xAddress 1000
cast decode-calldata "transfer(address,uint256)" 0xa9059cbb...

# 트랜잭션 정보 조회
cast tx 0xTxHash --rpc-url $MAINNET_RPC_URL

# ETH 단위 변환
cast to-unit 1000000000000000000 ether   # → 1.000000000000000000
cast from-wei 1000000000 gwei            # → 1.000000000

# 블록 정보
cast block latest --rpc-url $MAINNET_RPC_URL

# ===== chisel: Solidity REPL (실시간 Solidity 실행) =====
chisel
# > uint256 x = 100 * 1e18;
# > keccak256(abi.encodePacked("hello"))

# ===== MetaMask에 테스트넷 추가 방법 =====

# Sepolia 설정 (가장 많이 사용)
Network Name: Sepolia Testnet
RPC URL: https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
Chain ID: 11155111
Symbol: ETH
Block Explorer: https://sepolia.etherscan.io

# Hardhat 로컬 네트워크 설정 (개발용)
Network Name: Hardhat Local
RPC URL: http://127.0.0.1:8545
Chain ID: 31337
Symbol: ETH
Block Explorer: (없음)

# ===== Faucet으로 테스트 ETH 받기 =====
# 1. Alchemy Sepolia Faucet: https://sepoliafaucet.com
# 2. Chainlink Faucet: https://faucets.chain.link/sepolia
# 3. QuickNode Faucet: https://faucet.quicknode.com/ethereum/sepolia
# → 하루 0.1~0.5 SEP ETH 지급 (소셜 인증 필요할 수 있음)

// ignition/modules/Token.js — Ignition 배포 모듈
const { buildModule } = require("@nomicfoundation/hardhat-ignition/modules");

const TokenModule = buildModule("TokenModule", (m) => {
  // 배포 파라미터 (--parameters로 주입 가능)
  const initialOwner = m.getParameter("initialOwner");

  // 컨트랙트 배포
  const token = m.contract("BlockToken", [initialOwner]);

  // 배포 후 초기화 (선택)
  m.call(token, "mint", [initialOwner, ethers.parseEther("1000000")]);

  return { token };
});

module.exports = TokenModule;

# ===== Ignition 배포 명령어 =====

# 로컬 배포
npx hardhat ignition deploy ignition/modules/Token.js --network localhost

# Sepolia 배포 (파라미터 지정)
npx hardhat ignition deploy ignition/modules/Token.js   --network sepolia   --parameters '{"TokenModule":{"initialOwner":"0xYourAddress"}}'

# 배포 상태 확인
npx hardhat ignition status ignition/deployments/chain-11155111

# 검증 포함 배포
npx hardhat ignition deploy ignition/modules/Token.js   --network sepolia   --verify

# 배포 결과 (자동 생성)
# ignition/deployments/chain-11155111/deployed_addresses.json
{
  "TokenModule#BlockToken": "0xDeployedContractAddress..."
}

// ignition/modules/DeFiProtocol.js
const DeFiModule = buildModule("DeFiModule", (m) => {
  const owner = m.getParameter("owner");

  // 1. TokenA 배포
  const tokenA = m.contract("BlockToken", [owner], { id: "TokenA" });

  // 2. TokenB 배포
  const tokenB = m.contract("BlockToken", [owner], { id: "TokenB" });

  // 3. AMM 풀 배포 (TokenA, TokenB 주소 주입)
  const amm = m.contract("SimpleAMM", [tokenA, tokenB]);

  // 4. 초기 유동성 공급 (AMM 배포 후 실행)
  const approveA = m.call(tokenA, "approve", [amm, ethers.parseEther("100000")], {
    from: owner,
    after: [amm]
  });
  m.call(amm, "addLiquidity", [
    ethers.parseEther("10000"),
    ethers.parseEther("10000")
  ], { after: [approveA] });

  return { tokenA, tokenB, amm };
});

# ===== 방법 1: Hardhat verify 플러그인 (권장) =====

# 배포 후 자동 검증
npx hardhat verify --network sepolia 0xDeployedAddress "0xConstructorArg1" "arg2"

# 생성자 인자가 복잡한 경우 (배열, 구조체)
# scripts/verify-args.js 파일 생성
module.exports = [
  "BlockToken",
  "BTKN",
  ethers.parseEther("10000000")
];

npx hardhat verify --network sepolia 0xAddress --constructor-args scripts/verify-args.js

# ===== 방법 2: Etherscan 웹사이트 직접 업로드 =====
# 1. etherscan.io/address/0xAddress → Contract 탭
# 2. "Verify and Publish" 클릭
# 3. Compiler Type: Solidity (Single File / Multi-Part)
# 4. Compiler Version: 0.8.20
# 5. Optimization: Yes, 200 runs
# 6. 소스코드 붙여넣기 → Verify

# ===== 방법 3: Foundry verify =====
forge verify-contract 0xDeployedAddress src/BlockToken.sol:BlockToken   --chain sepolia   --etherscan-api-key $ETHERSCAN_API_KEY   --constructor-args $(cast abi-encode "constructor(address)" 0xOwner)

// scripts/upload-to-ipfs.js
const { PinataSDK } = require("pinata");
const fs             = require("fs");
const path           = require("path");
require("dotenv").config();

const pinata = new PinataSDK({
  pinataJwt:     process.env.PINATA_JWT,
  pinataGateway: process.env.PINATA_GATEWAY_URL
});

async function uploadNFTCollection(imageDir, count) {
  const imageHashes   = [];
  const metadataHashes = [];

  // 1단계: 이미지 일괄 업로드
  console.log("📸 이미지 업로드 중...");
  for (let i = 1; i <= count; i++) {
    const imgPath = path.join(imageDir, `${i}.png`);
    const file = new File(
      [fs.readFileSync(imgPath)],
      `${i}.png`,
      { type: "image/png" }
    );
    const result = await pinata.upload.file(file);
    imageHashes.push(result.IpfsHash);
    console.log(`  ✅ ${i}.png → ipfs://${result.IpfsHash}`);
  }

  // 2단계: 메타데이터 JSON 생성 및 업로드
  console.log("📝 메타데이터 업로드 중...");
  for (let i = 1; i <= count; i++) {
    const metadata = {
      name:         `BlockchainNFT #${i}`,
      description:  "A unique blockchain developer collectible",
      image:        `ipfs://${imageHashes[i-1]}`,
      external_url: `https://myproject.io/nft/${i}`,
      attributes: [
        { trait_type: "Rarity",   value: getRarity(i)    },
        { trait_type: "Level",     value: getLevel(i)     },
        { trait_type: "Token ID",  value: i               }
      ]
    };
    const result = await pinata.upload.json(metadata);
    metadataHashes.push(result.IpfsHash);
    console.log(`  ✅ Metadata #${i} → ipfs://${result.IpfsHash}`);
  }

  // 3단계: 결과 저장
  fs.writeFileSync("./ipfs-hashes.json", JSON.stringify({ imageHashes, metadataHashes }, null, 2));
  console.log("✨ 업로드 완료! ipfs-hashes.json 저장됨");
  return metadataHashes;
}

function getRarity(id) {
  if (id <= 10)  return "Legendary";
  if (id <= 50)  return "Epic";
  if (id <= 200) return "Rare";
  return "Common";
}
function getLevel(id) { return Math.floor(Math.random() * 100) + 1; }

uploadNFTCollection("./images", 1000).catch(console.error);

// npm install @openzeppelin/hardhat-upgrades @openzeppelin/contracts-upgradeable

// contracts/TokenV1.sol — UUPS 업그레이더블 토큰
import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract TokenV1 is Initializable, ERC20Upgradeable, OwnableUpgradeable, UUPSUpgradeable {
    // ⚠️ constructor 대신 initialize 사용!
    function initialize(address initialOwner) public initializer {
        __ERC20_init("BlockToken", "BTKN");
        __Ownable_init(initialOwner);
        __UUPSUpgradeable_init();
        _mint(initialOwner, 10_000_000 ether);
    }

    function _authorizeUpgrade(address) internal override onlyOwner {}
}

// contracts/TokenV2.sol — 새 기능 추가 버전
contract TokenV2 is TokenV1 {
    uint256 public version;

    function initializeV2() public reinitializer(2) {
        version = 2;
    }

    // 새로운 기능 추가
    function newFeature() external pure returns (string memory) {
        return "V2 Feature!";
    }
}

// scripts/deploy-upgradeable.js
const { ethers, upgrades } = require("hardhat");

async function main() {
  const [deployer] = await ethers.getSigners();

  // V1 배포 (UUPS 프록시와 함께)
  const TokenV1 = await ethers.getContractFactory("TokenV1");
  const proxy = await upgrades.deployProxy(TokenV1, [deployer.address], {
    initializer: "initialize",
    kind: "uups"
  });
  await proxy.waitForDeployment();
  console.log("Proxy 주소 (변하지 않음):", await proxy.getAddress());

  // V2로 업그레이드
  const TokenV2 = await ethers.getContractFactory("TokenV2");
  const upgraded = await upgrades.upgradeProxy(proxy, TokenV2);
  await upgraded.initializeV2();
  console.log("✅ V2로 업그레이드 완료! 주소 동일", await upgraded.getAddress());
}

main().catch(console.error);

// .solhint.json — 린팅 규칙
{
  "extends": "solhint:recommended",
  "rules": {
    "compiler-version": ["error", "^0.8.20"],
    "reentrancy":       "error",
    "avoid-call-value": "error",
    "max-line-length":  ["warn", 120]
  }
}

// package.json scripts
{
  "scripts": {
    "test":     "hardhat test",
    "coverage": "hardhat coverage",
    "lint":     "solhint contracts/**/*.sol",
    "gas":      "REPORT_GAS=true hardhat test",
    "deploy:sepolia": "hardhat ignition deploy ignition/modules/Token.js --network sepolia --verify"
  }
}

📌 다음 편 예고: BlockchainDevGuide0005

NFT · DeFi 심화 — 실전 프로젝트 완성

NFT 마켓플레이스 · ERC-1155 게임아이템 · Uniswap V3 통합 · Aave 대출 프로토콜 · DAO 거버넌스