> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM 테스트 도구

## 목적 및 범위

이 페이지는 EVM 바이트코드 실행, 상태 전환 및 트랜잭션 검증을 위해 StableNet에서 제공하는 테스트 및 디버깅 도구를 설명합니다.\
이 도구들은 스마트 컨트랙트 개발, 합의 규칙 검증, 트랜잭션 실행 디버깅을 수행하는 개발자에게 필수적인 실무 도구입니다.

핵심 도구는 `cmd/evm` 유틸리티로, 다양한 테스트 시나리오를 지원하는 여러 하위 명령을 제공합니다.\
본 문서는 명령줄 기반 도구와 프로그래밍 방식 테스트 인터페이스를 다룹니다.

보다 포괄적인 테스트 인프라와 JSON 테스트 픽스처에 대한 내용은\
[테스트 프레임워크](/ko/development-tools/10.4-testing-framework)을 참고하세요.

## 명령줄 도구 개요

`evm` 명령줄 도구는 전체 노드를 실행하지 않고도 EVM 바이트코드, 트랜잭션, 상태 전환을 테스트할 수 있는 격리된 실행 환경을 제공합니다.\
모든 명령은 다양한 추적(trace) 및 디버깅 옵션을 지원합니다.

### 사용 가능한 명령

* `evm run`
* `evm transition` (`t8n`)
* `evm transaction` (`t9n`)
* `evm block-builder` (`b11r`)
* `evm blocktest`

## evm run 명령

`run` 명령은 구성 가능한 상태 및 블록 컨텍스트를 가진 격리된 환경에서 임의의 EVM 바이트코드를 실행합니다.

### 주요 플래그

| Flag          | Type    | Default     | Description          |
| ------------- | ------- | ----------- | -------------------- |
| `--code`      | string  | -           | 16진수 EVM 바이트코드       |
| `--codefile`  | string  | -           | 바이트코드 파일(`-`는 stdin) |
| `--input`     | string  | -           | 호출 데이터(hex)          |
| `--inputfile` | string  | -           | 호출 데이터 파일            |
| `--gas`       | uint64  | 10000000000 | 가스 한도                |
| `--price`     | big.Int | 0           | 가스 가격                |
| `--value`     | big.Int | 0           | 전송 값                 |
| `--sender`    | address | default     | 발신자 주소               |
| `--receiver`  | address | default     | 수신자 주소               |
| `--create`    | bool    | false       | CALL 대신 CREATE 사용    |
| `--prestate`  | string  | -           | 상태 초기화용 genesis JSON |
| `--debug`     | bool    | false       | 전체 트레이스 출력           |
| `--json`      | bool    | false       | JSON 출력              |
| `--dump`      | bool    | false       | 실행 후 상태 덤프           |
| `--bench`     | bool    | false       | 벤치마크 실행              |

### 실행 프로세스

`runCmd`는 다음 순서로 실행을 조정합니다.

1. 제네시스 또는 빈 상태로 StateDB 초기화
2. 바이트코드 로딩(`--code`, `--codefile`, 위치 인수)
3. 발신자·수신자 계정 설정
4. 가스, 가격, 블록 컨텍스트로 `runtime.Config` 구성
5. `Execute`, `Call`, `Create` 중 하나 실행
6. 실행 결과, 가스 사용량, 선택적 트레이스 출력

## evm transition (t8n) 명령

`transition` 명령은 Ethereum 상태 전환 함수를 구현하여 사전 상태에 트랜잭션 집합을 적용하고 사후 상태를 생성합니다.\
합의 레벨 트랜잭션 처리를 검증하는 핵심 도구입니다.

### 입력 형식

`t8n`은 다음 세 가지 입력을 요구합니다.

* **alloc.json**: 사전 상태 계정 할당
* **env.json**: 블록 환경 정보
* **txs.json** 또는 `txs.rlp`: 트랜잭션 목록

### 출력 형식

* **alloc.json**: 사후 상태
* **result.json**: 실행 결과
* **body.rlp**: 블록 본문(옵션)

### 주요 플래그

| Flag               | Default     | Description |
| ------------------ | ----------- | ----------- |
| `--input.alloc`    | stdin       | 사전 상태 할당    |
| `--input.env`      | stdin       | 블록 환경       |
| `--input.txs`      | stdin       | 트랜잭션        |
| `--output.basedir` | -           | 출력 디렉터리     |
| `--output.alloc`   | alloc.json  | 사후 상태       |
| `--output.result`  | result.json | 실행 결과       |
| `--output.body`    | body.rlp    | 블록 본문       |
| `--state.fork`     | -           | 포크 이름       |
| `--state.chainid`  | 1           | 체인 ID       |
| `--state.reward`   | -1          | 마이닝 보상      |
| `--trace`          | false       | JSON 트레이스   |
| `--trace.tracer`   | -           | 커스텀 트레이서    |

### 포크 구성

`--state.fork`는 적용할 합의 규칙을 지정합니다.

* `Frontier`, `Homestead`, `EIP150`, `EIP158`
* `Byzantium`, `Constantinople`, `Istanbul`
* `Berlin`, `London`, `Shanghai`, `Cancun`
* `Anzeon` (StableNet 전용)

추가 EIP는 `London+3855+3860` 형태로 지정할 수 있습니다.

### 환경 검증 규칙

활성 포크에 따라 필수 필드가 검증됩니다.

* London: `currentBaseFee` 또는 `parentBaseFee` 필요
* Shanghai: `withdrawals` 필요
* Merge: `currentRandom` 필요, 난이도 0
* Cancun: `parentBeaconBlockRoot` 필요

## evm transaction (t9n) 명령

`t9n` 명령은 트랜잭션을 실행하지 않고 인코딩 및 서명 복구를 검증합니다.

### 검증 항목

1. RLP 디코딩 가능 여부
2. ECDSA 서명을 통한 발신자 복구
3. 포크별 검증 규칙 준수

### 주요 플래그

| Flag              | Default | Description |
| ----------------- | ------- | ----------- |
| `--input.txs`     | stdin   | 트랜잭션 입력     |
| `--state.fork`    | -       | 포크 규칙       |
| `--state.chainid` | 1       | 체인 ID       |

## evm block-builder (b11r) 명령

`block-builder`는 트랜잭션, ommer, withdrawal 정보를 이용해 완전한 블록을 구성합니다.

### 주요 플래그

| Flag                  | Default | Description   |
| --------------------- | ------- | ------------- |
| `--input.header`      | -       | 헤더 템플릿        |
| `--input.txs`         | -       | 트랜잭션 RLP      |
| `--input.ommers`      | -       | Uncle 헤더      |
| `--input.withdrawals` | -       | Withdrawal 목록 |
| `--output.block`      | -       | 출력 블록 RLP     |
| `--seal.clique`       | -       | Clique 서명 키   |

## evm blocktest 명령

`blocktest`는 JSON 형식의 블록체인 테스트를 실행하여 블록 유효성 및 상태 전환을 검증합니다.\
테스트 구조와 실행 로직은 테스트 프레임워크와 동일한 규칙을 따릅니다.

## 테스트 프레임워크 연계

`evm` 도구는 내부적으로 `tests` 패키지의 실행 로직을 재사용합니다.

### 주요 테스트 함수

| Function                  | Purpose      |
| ------------------------- | ------------ |
| `StateTest.Run()`         | State 테스트 실행 |
| `StateTest.RunNoVerify()` | 검증 없이 실행     |
| `BlockTest.Run()`         | Block 테스트 실행 |
| `TransactionTest.Run()`   | 트랜잭션 검증      |
| `MakePreState()`          | 사전 상태 생성     |
| `GetChainConfig()`        | 포크 구성 파싱     |

## EVM Runtime 패키지

`core/vm/runtime` 패키지는 블록체인 인프라 없이 EVM을 실행하기 위한 프로그래밍 인터페이스를 제공합니다.

### 기본 동작

`runtime.Config`는 합리적인 기본값을 제공합니다.

* 모든 하드 포크 활성화
* Difficulty 0 (병합 이후)
* GasLimit 최대값
* BaseFee 1 gwei
* BlobBaseFee 1 wei

### 상태 준비 단계

실행 전 다음 작업이 수행됩니다.

1. 액세스 리스트 워밍업(Post-Berlin)
2. 임시 저장소 초기화(EIP-1153)
3. 프리컴파일 주소 워밍업
4. 트랜잭션 관련 주소 워밍업

## 테스트 워크플로우 요약

EVM 테스트 도구는 다음 흐름으로 사용됩니다.

1. 단일 바이트코드 테스트(`evm run`)
2. 합의 규칙 검증(`evm transition`)
3. 트랜잭션 형식 검증(`evm transaction`)
4. 블록 구성 및 검증(`evm block-builder`, `evm blocktest`)

이를 통해 전체 노드를 실행하지 않고도 EVM 및 합의 로직을 정밀하게 검증할 수 있습니다.