> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/ko/canton-zk-evm/run-it-locally.md).

# 자신만의 Ostia 실행

검증, GPU 없이 하는 리허설, GPU에서의 로컬 데모, 재시작 후에도 유지되는 체인, 그리고 기존 Canton 참가자 위의 Ostia를 실행합니다.

기본적으로 제공된 스크립트는 로컬 테스트 네트워크를 실행합니다. Canton은 상태를 메모리에 보관하므로 다시 시작할 때마다 해당 상태가 삭제되고 새 네트워크가 생성됩니다. 체인을 유지하는 두 가지 모드는 영구 모드(`CZE_PERSIST=1`)와 기존 Canton 참여자에서 Ostia를 실행하는 모드입니다. Ostia DevNet은 후자의 방식으로 실행됩니다. GPU 데모는 블록을 증명합니다. 리허설은 대체 증명을 사용하며 GPU가 필요하지 않습니다.

이 페이지에서는 릴리스 `v0.1.0`을 설명합니다. 전체 [네트워크 가이드](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) 와 [데모 가이드](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md)를 참조하세요. 아래 명령은 `canton-zk-evm` 리포지토리 루트에서 실행하세요.

## 필요한 항목

| 작업            | 요구 사항                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------- |
| 리포지토리 검사      | Docker, `bash`, `curl`, `jq`, `openssl` 및 Python 3. Rust 테스트는 `rust-toolchain.toml`.              |
| Canton 통합 테스트 | Linux x86-64, Java 21 및 네트워크 액세스.                                                                 |
| 데모 리허설        | Linux x86-64, Docker, Java 21, Rust 및 Python 3.12 이상.                                             |
| 익스플로러 테스트     | Node 22.18 이상.                                                                                    |
| GPU 네트워크 및 데모 | Linux x86-64, 드라이버가 설치된 NVIDIA GPU, Docker, Rust, Python 3.12 이상, `jq`, `curl`, `openssl` 및 ZisK. |

테스트 필수 요건은 [리포지토리 README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) 에 나열되어 있습니다. GPU 설치 프로그램은 Debian 또는 Ubuntu에서 `sudo` 와 `apt` 를 사용하며 약 100GB의 여유 디스크 공간이 필요합니다. 시스템 패키지를 설치하고 메모리 잠금 제한을 변경합니다. 네트워크의 도구 가져오기 프로그램은 Java 21이 없으면 이를 설치합니다. 테스트된 하드웨어는 [Ostia 증명자 호스트](https://docs.rome.builders/ko/canton-zk-evm/prover-host.md) 를 참조하세요. 최소 GPU 메모리 요구량은 아직 정해지지 않았습니다.

## 테스트 실행

다음 문서의 빠른 검사부터 시작하세요. [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # 고정된 버전, 제네시스 및 라이선스 항목이 일치하는지 확인
tests/refuses_missing_flag.sh    # 플래그가 없거나 잘못된 경우 reth 실행이 거부되는지 확인
tests/fixtures.sh                # 기록된 증명이 일관되는지 확인
gateway/build.sh --check         # 체크인된 게이트웨이 코드가 Gateway.sol이 컴파일되는 코드인지 확인 (Docker)
```

저장소 README에도 다음 검사 방법이 안내되어 있습니다. GPU는 필요하지 않습니다.

```sh
tests/udp_control.sh             # UDP 리스너가 있는 컨테이너에서는 UDP 검사가 실패합니다 (reth 불필요)
tests/discovery.sh               # 고정 버전의 reth를 시작하고, 피어가 없는지 확인한 뒤 종료합니다
tests/network_static.sh          # launch.sh를 통한 reth 실행, Canton 설정, 기록된 스모크 테스트 결과만 확인합니다
tests/network_checks.sh          # 컴파일러 버전 고정, DAR ID, 다른 programVK에서의 중지를 확인합니다 (GPU 불필요)
tests/canton_network.sh          # 고정 버전 Canton, 실제 Daml 패키지, Advance 1회 확인 (Linux x86-64, Java 21, Python 3; GPU 불필요)
gateway/tests/run.sh             # 피어 검색을 끈 상태로 시작한 실제 reth에서 게이트웨이를 테스트합니다 (Docker, curl, jq, demo/requirements.txt에 명시된 패키지가 설치된 Python 3)
tests/guest-repro.sh             # 게스트 빌드가 하나의 고정 폴더에서 실행되므로 소스 폴더가 ELF에 영향을 주지 않습니다 (ZisK 도구 대체품 사용; 실제 ZisK에서도 같은 검사를 2026-10-04에 통과했습니다. guest/README.md 참고)
tests/demo_static.sh             # 데모의 버전 고정, 변조 스위치와 제네시스 재정의, 기록된 결과를 확인합니다 (GPU 불필요)
tests/demo_explorer_static.sh    # 익스플로러 이미지가 고정되어 있는지, 컨테이너에 전달되는 항목을 확인합니다 (Docker 불필요)
(cd explorer && npm ci && npm test)  # 가짜 객체를 사용해 익스플로러 테스트를 실행합니다 (Node 22.18 이상; CI는 PINS의 EXPLORER_NODE_IMAGE 사용)
(cd guest/rules && cargo test)   # 체인 규칙과 해시를 확인합니다 (Rust 필요)
```

## GPU 없이 리허설 실행

```sh
tests/demo_rehearsal.sh          # 대체 증명을 사용해 데모와 익스플로러를 실행합니다 (Linux x86-64, Docker, Java 21, Rust, Python 3.12 이상; GPU 불필요)
```

이 검사는 실제 reth, Canton, Daml 패키지, 토큰 표준 및 빌더를 실행합니다. 사이드카는 게이트웨이의 각 단계를 스토리지 증명과 대조하고, 대체 구성 요소는 증명의 `verify` 호출에 응답합니다. 이 리허설은 블록을 증명하지 않으며 실제 영지식 증명을 검증하지도 않습니다.

익스플로러와 수도꼭지도 확인합니다. 익스플로러의 Verify 검사는 대체 증명을 거부해야 합니다. 자세한 내용은 [데모 README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) 에서 리허설의 테스트 범위를 확인하세요.

## GPU에서 로컬 네트워크 시작

네트워크를 시작하기 전에 다음 명령으로 ZisK를 설치하세요: `prover/install.sh` 네트워크를 시작하기 전에 ZisK를 설치하세요. reth는 항상 제공된 실행 스크립트를 통해 시작해야 합니다. `network/up.sh` 에서 해당 스크립트를 사용합니다.

```sh
network/up.sh       # 도구, 게스트 빌드, reth, 사이드카, 증명기, Canton, 체인
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # 빈 블록 하나를 증명하고 커밋합니다
network/down.sh
```

`up.sh` 는 게스트를 빌드하며, program key, ZisK 루트 또는 규칙 해시가 기록된 값과 다르면 실행을 거부합니다. 네트워크에는 동기화기 하나와 참여자 세 명이 있습니다. 운영자 참여자와 확인자 참여자는 각각 사이드카를 실행합니다. users라는 참여자는 테스트 파티와 리더를 호스팅합니다.

스모크 테스트는 빈 블록을 커밋하고 체인의 헤드와 리더의 블록 기록을 확인하며, reth가 해당 블록을 최종 상태로 표시했는지도 확인합니다. 상태와 로그는 `state/`에 저장됩니다. 다음 변수가 설정되어 있으면 `CZE_STATE_DIR` 에 저장됩니다.

## GPU에서 데모 사례 다섯 가지 실행

데모를 위해 새 로컬 네트워크를 사용하세요.

```sh
demo/prepare.sh
CZE_GENESIS_FILE=$PWD/state/demo/genesis.json network/up.sh
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh      # 선택 사항: 먼저 빈 블록 하나를 커밋합니다
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

준비 스크립트는 실행에 사용할 테스트 키와 자금이 충전된 제네시스를 생성합니다. 데모는 설정 블록, 입금, 결제, 출금, 할당 거부, 변조된 증명 거부를 실행합니다. 검사에 실패하면 스크립트는 중단되고 결과를 `demo/results/`.

.git `이 없는 소스 내보내기를 사용하는 경우`을 설정하고 `CZE_SOURCE_COMMIT` 에 내보내기에 사용한 커밋의 전체 해시를 지정하세요. 수도꼭지를 포함하려면 네트워크를 시작하기 전에 자금이 충전된 제네시스를 준비해야 합니다. 자세한 내용은 [탐색기를 직접 실행하기](#run-the-explorer-yourself) 아래 내용과 전체 데모 가이드를 참고하세요.

## 재시작 후에도 체인 유지하기

사용 중인 체인은 충돌이나 재부팅 후에도 유지되어야 합니다. `up.sh` 는 영구 모드를 지정하지 않으면 실행할 때마다 새 체인을 만듭니다.

```sh
CZE_PERSIST=1 network/up.sh     # 첫 시작: 새 체인을 만들고 유지
network/down.sh                 # 모든 항목을 중지하고 데이터를 유지
network/restart.sh              # 재부팅 후: 기존 체인을 다시 시작
network/down.sh --wipe          # 모든 항목을 중지하고 체인을 완전히 삭제
```

Canton은 127.0.0.1의 PostgreSQL에 노드를 저장하며, 비밀번호는 해당 머신에서 생성되어 권한이 0600인 파일에 저장됩니다. reth는 데이터를 `$CZE_STATE_DIR/reth-data` 에 저장하고 블록을 가져올 때마다 디스크에 기록합니다. `restart.sh` 는 아무것도 새로 생성하지 않습니다. 기존 데이터를 사용하여 데이터베이스, reth, 사이드카, 프로버, Canton을 시작하고 reth를 Canton의 헤드로 이동시킵니다. 데이터베이스가 `PINS`에 지정된 버전과 다른 Canton 버전으로 생성된 경우에는 중지됩니다. 네트워크를 중지한 상태에서 데이터베이스와 `reth-data` 를 함께 백업하세요. 모든 사례는 [네트워크 가이드](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) 에서 확인할 수 있습니다.

## 기존 참가자에서 실행하기

Ostia는 로컬 네트워크 대신 Canton Network DevNet의 Splice 검증자와 같이 이미 존재하는 Canton 참가자에서 실행할 수 있습니다. Ostia DevNet도 이 방식으로 실행됩니다. `up.sh` 는 이 경우 reth와 프로버, 그리고 요청한 경우 사이드카 하나를 시작하고 해당 참가자에 체인을 설정합니다. Canton은 시작하지 않으며 부트스트랩도 수행하지 않습니다.

필요한 항목은 다음과 같습니다.

* 참가자의 JSON Ledger API(v2) 주소. 같은 머신의 `https` URL 또는 `http` URL이어야 합니다.
* Ledger API 사용자 네 명 각각의 토큰 파일: `ADMIN` (패키지를 업로드하고 파티와 사용자를 생성하므로 `up.sh` 와 `setup.py` 에만 필요) 및 `OPERATOR`, `CONFIRMER` 와 `BUILDER` (생성되는 사용자: `setup.py` 생성되는 사용자: `ostia-operator`, `ostia-confirmer` 와 `ostia-builder`). 각 토큰은 HS256을 사용하며 audience는 `https://canton.network.global` 이고 사용자 ID는 다음 필드에 지정합니다: `sub` 참가자를 실행하는 주체가 토큰을 만듭니다. Ostia는 토큰을 만들거나 출력하거나 저장하지 않습니다.
* 참가자만 접근할 수 있고 다른 누구도 접근할 수 없는 사이드카입니다.

토큰은 수명이 짧으므로 새 토큰이 생길 때마다 같은 파일에 덮어써서 기록하세요. 빌더는 호출할 때마다 파일을 다시 읽습니다. `setup.py` 및 `propose.py` 는 각 토큰을 한 번만 읽으므로, 새 토큰을 발급한 뒤 실행하세요.

먼저 참가자에게 필요한 줄을 컨테이너의 추가 `ADDITIONAL_CONFIG` 변수로 제공한 다음, 참가자를 다시 시작하세요:

```sh
network/external/participant-config.sh <sidecar address> 8085
# 출력: ADDITIONAL_CONFIG_ZK_EVM=canton.participants.participant.parameters.engine.extensions.canton-zk-evm { address = "<sidecar address>", port = 8085, validate-on-startup = false }
```

다음과 같이 `validate-on-startup` 를 false로 설정하면 sidecar가 중지되어 있어도 participant가 계속 시작됩니다. 이 경우 블록 검사가 실패하여 어떤 블록도 커밋되지 않습니다. 그런 다음 체인을 시작합니다:

```sh
export CZE_CANTON=external CZE_LEDGER_URL=https://<participant's Ledger API>
export CZE_TOKEN_FILE_ADMIN=... CZE_TOKEN_FILE_OPERATOR=... \
       CZE_TOKEN_FILE_CONFIRMER=... CZE_TOKEN_FILE_BUILDER=...
CZE_PERSIST=1 CZE_SIDECAR_LISTEN=<sidecar address>:8085 network/up.sh
```

`CZE_PERSIST=1` 여기서 필수입니다. 체인이 참여자에 남아 있고 reth도 블록을 보관해야 하기 때문입니다. 사이드카가 다른 머신에서 실행된다면, 그 머신에서 다음 명령으로 시작하고 `network/external/sidecar.sh start <sidecar address>:8085` (참여자가 접속하는 주소이며, 공개 주소가 아님) 다음을 실행합니다. `up.sh` 다음 없이 `CZE_SIDECAR_LISTEN`. `up.sh` 게스트를 빌드하고, reth와 증명 생성기를 시작한 다음 `external/setup.py`를 실행합니다. 이 스크립트는 패키지를 업로드하고, 참여자들을 할당하고, 각 사용자에게 해당 역할의 권한만 부여해 생성한 뒤 체인을 제안합니다. 두 번 실행해도 문제가 없습니다. `restart.sh` 체인을 복원하며 빌더의 토큰만 있으면 됩니다. `down.sh --wipe` 참가자에는 영향을 주지 않습니다. 체인의 컨트랙트는 운영자가 제거할 때까지 그대로 남아 있습니다.

이 모드에는 다음 세 가지 규칙이 적용됩니다.

* **Ledger API를 절대 외부에 노출하지 마세요.** 참가자가 호스팅하는 모든 당사자처럼 동작할 수 있습니다. 머신 자체의 주소에서만 사용하거나, 호출자를 확인하는 프록시 뒤에 두세요.
* **토큰 파일의 권한을 0600으로 설정하고**, 공유 머신에는 두지 마세요.
* **참가자의 운영자는 모든 것을 볼 수 있습니다.** 한 참가자가 모든 Ostia 당사자를 호스팅하므로, 운영자는 모든 컨트랙트를 읽고 모든 당사자를 대신해 동작할 수 있으며, 게이트웨이의 자금 보관 기능도 예외가 아닙니다. 이 참가자의 유일한 확인자는 단 하나의 사이드카입니다. Ostia DevNet에서 그 운영자는 Rome입니다. Rome은 참가자와 자체 Canton DevNet 검증자를 실행합니다.

## 빌더를 계속 실행하기

`builder.py once` 블록 하나를 생성합니다. `builder.py run` 블록을 계속 생성합니다.

```sh
python3 builder/builder.py run [--heartbeat-seconds N] [--status-file <path>]
```

동일한 [설정](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) 을 읽습니다. 이는 `once`. 기본 전략인 `on_demand`에서는 처리할 수 있는 트랜잭션이 대기 중일 때마다 블록을 생성하며, 기본적으로 한 번에 하나의 블록만 처리 중 상태로 둡니다(`--max-in-flight` 로 늘릴 수 있습니다). 조용한 체인에서는 `--heartbeat-seconds N` 을 설정하지 않는 한 블록을 생성하지 않습니다. 이 옵션을 설정하면 N초 동안 블록이 없을 때 빈 블록을 요청합니다. 기본값은 하트비트 없음입니다. 블록 생성이 연속 두 번 거부되면 빌더는 트랜잭션에 문제가 있다고 판단하고 쿨다운 기간 동안 제외합니다.

빌더는 한 번에 하나만 실행할 수 있습니다. `run` 과 `once` 는 잠금을 획득하며, 다른 프로세스가 잠금을 보유 중이면 시작을 거부합니다. 종료 신호를 받으면 진행 중인 블록 처리를 마친 뒤 종료합니다. 빌더는 서비스 관리자에서 실행하고, 증명 생성 시간과 Canton의 응답 시간을 합친 것보다 긴 종료 대기 시간을 설정해 재시작하도록 하세요. 언제든 안전하게 재시작할 수 있습니다. 다음 실행은 Canton의 헤드부터 다시 시작하고, 중단된 블록의 트랜잭션을 reth에 다시 보냅니다. 빌더는 작업 폴더에 `status.json` 과 저널을 기록하며, 탐색기는 둘 다 읽습니다.

## 탐색기를 직접 실행하기

탐색기는 표시 대상 체인과 함께 컨테이너로 실행되며, Docker가 설치된 Linux 머신이 필요합니다. 탐색기 전용 PostgreSQL 데이터베이스는 `network/explorer-db.sh`가 시작하며, 인덱서는 Canton의 기록을 가져와 이 데이터베이스를 채웁니다. 네트워크가 시작되기 전에 제네시스에 수도꼭지의 자금이 들어 있어야 하므로, `setup` 을 먼저 실행합니다.

```sh
explorer/run.sh setup           # 수도꼭지 키와 자금이 들어 있는 제네시스를 생성합니다
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # 그런 다음 http://127.0.0.1:8088을 엽니다
explorer/run.sh stop
```

`start` 는 데이터베이스를 시작하고 마이그레이션을 적용한 다음, 인덱서를 별도 컨테이너로 실행하고 이어서 탐색기를 시작합니다. 수도꼭지 키가 없으면 수도꼭지는 비활성화됩니다. 수도꼭지 지급은 reth로 보내는 트랜잭션이므로 빌더가 실행될 때만 최종 확정됩니다. 네트워크나 탐색기를 시작해도 빌더는 시작되지 않습니다. explorer/run.sh start를 실행하기 전에 빌더를 한 번 실행하거나, `explorer/run.sh start`를 실행한 뒤 빌더를 처음 실행한 다음 다시 실행하세요. 그전까지 탐색기에는 빌더 작업 폴더가 없으며 블록 수명 주기 정보도 표시되지 않습니다. 네트워크를 `start` 없이 만든 경우 `CZE_PERSIST`, `stop` 은 수도꼭지 요청과 검증된 컨트랙트 소스가 들어 있는 탐색기 데이터베이스도 삭제합니다. 영구 네트워크에서는 데이터베이스가 유지됩니다.

기본 설정의 `explorer/run.sh start` 에서는 `EXPLORER_VERIFIER=1` (및 `SOLC_LIST_URL`)을 설정하지 않으면 컨트랙트 검증이 비활성화됩니다. 또한 `/rpc` 와 컨트랙트 읽기 호출은 `PUBLIC_RPC=1`을 설정하지 않으면 사용할 수 없습니다. 설정은 [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

의 헤더에 나열되어 있습니다. 제공된 로컬 네트워크에서는 Ledger API에 로그인 절차가 없습니다. 탐색기는 리더 파티로만 읽기 작업을 하지만, 해당 참여자에 접속할 수 있는 누구나 다른 파티의 데이터도 읽을 수 있으므로 컨테이너에 공개 주소를 절대 할당하지 마세요. 기존 참여자에서 탐색기를 사용하려면 리더 사용자용 권한 모드가 0600인 토큰 파일(`LEDGER_TOKEN_FILE`), 참여자의 `LEDGER_URL` 및 `READER_PARTY`. 컨테이너는 여전히 127.0.0.1에서 수신 대기하므로, 공개 주소를 사용하려면 직접 프록시를 설정해야 합니다. 자세한 내용은 [탐색기 가이드](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) 에서 모든 설정을 확인할 수 있습니다.

## 현실적인 트래픽 구성으로 로드 테스트를 실행하려면

`load/mixed` 에 1시간 실행 테스트에 사용되는 도구 모음이 있습니다. 자세한 내용은 [측정](https://docs.rome.builders/ko/canton-zk-evm/measurements.md). 이 도구는 체인에 여러 종류의 토큰과 DEX, 권한형 토큰, 비공개 전송 컨트랙트를 배포한 다음 200개의 지갑에서 다양한 트래픽을 전송합니다. 자세한 실행 단계는 [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) 에 있습니다. Docker와, 제공된 기본 설정으로 도구를 실행할 경우 약 12,000 tROME을 보유한 계정이 필요합니다. 자체 체인에서는 제네시스에 자금을 넣으세요. DevNet 수도꼭지에서는 그만큼의 자금을 제공할 수 없습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/ko/canton-zk-evm/run-it-locally.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
