> 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/vi/canton-zk-evm/run-it-locally.md).

# Chạy Ostia của riêng bạn

Chạy các kiểm tra, buổi diễn tập không có GPU, bản demo cục bộ trên GPU, một chuỗi vẫn tồn tại sau khi khởi động lại và Ostia trên một participant Canton hiện có.

Theo mặc định, các tập lệnh được cung cấp chạy một mạng kiểm thử cục bộ. Canton lưu trạng thái trong bộ nhớ, vì vậy mỗi lần khởi động lại sẽ xóa trạng thái đó và tạo một mạng mới. Hai chế độ khác duy trì một chuỗi: chế độ bền vững (`CZE_PERSIST=1`) và Ostia trên một Canton participant mà bạn đã có; đây là cách Ostia DevNet hoạt động. Bản demo GPU chứng minh các khối. Buổi diễn tập dùng một bằng chứng thay thế và không cần GPU.

Trang này mô tả bản phát hành `v0.1.0`. Đọc toàn bộ [hướng dẫn về mạng](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) và [hướng dẫn bản demo](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md). Chạy các lệnh bên dưới từ `canton-zk-evm` thư mục gốc của kho lưu trữ.

## Yêu cầu

| Công việc                | Yêu cầu                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Kiểm tra kho lưu trữ     | Docker, `bash`, `curl`, `jq`, `openssl` và Python 3. Các bài kiểm thử Rust sử dụng `rust-toolchain.toml`.             |
| Kiểm thử tích hợp Canton | Linux x86-64, Java 21 và quyền truy cập mạng.                                                                         |
| Diễn tập bản demo        | Linux x86-64, Docker, Java 21, Rust và Python 3.12 trở lên.                                                           |
| Kiểm thử Explorer        | Node 22.18 trở lên.                                                                                                   |
| Mạng và bản demo GPU     | Linux x86-64, GPU NVIDIA đã cài trình điều khiển, Docker, Rust, Python 3.12 trở lên, `jq`, `curl`, `openssl` và ZisK. |

Tệp [README của kho lưu trữ](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) liệt kê các yêu cầu tiên quyết để chạy kiểm thử. Trình cài đặt GPU sử dụng `sudo` và `apt` trên Debian hoặc Ubuntu và cần khoảng 100 GB dung lượng đĩa trống. Trình cài đặt này cài đặt các gói hệ thống và thay đổi giới hạn khóa bộ nhớ. Trình tải công cụ của mạng sẽ cài Java 21 nếu máy chưa có. Xem [máy chủ prover Ostia](https://docs.rome.builders/vi/canton-zk-evm/prover-host.md) để biết phần cứng đã được kiểm thử; yêu cầu tối thiểu về bộ nhớ GPU chưa được xác định.

## Chạy kiểm thử

Bắt đầu với các bước kiểm tra nhanh trong [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # các dòng ghim phiên bản, genesis và giấy phép phải thống nhất
tests/refuses_missing_flag.sh    # lệnh khởi chạy reth từ chối khi thiếu cờ hoặc cờ sai
tests/fixtures.sh                # bằng chứng đã ghi nhận phải nhất quán
gateway/build.sh --check         # mã nguồn gateway đã commit là mã được biên dịch thành Gateway.sol (Docker)
```

README của kho lưu trữ cũng nêu các bước kiểm tra sau. Không cần GPU:

```sh
tests/udp_control.sh             # bước kiểm tra UDP thất bại trên container có trình lắng nghe UDP (không có reth)
tests/discovery.sh               # khởi chạy reth đã ghim phiên bản, kiểm tra không có peer nào, rồi dừng nó
tests/network_static.sh          # chỉ chạy reth thông qua launch.sh, dùng cấu hình Canton và kết quả kiểm tra khói đã ghi lại
tests/network_checks.sh          # kiểm tra phiên bản compiler đã ghim, ID của DAR và việc dừng khi dùng programVK khác (không cần GPU)
tests/canton_network.sh          # Canton đã ghim phiên bản, gói Daml thực và một Advance (Linux x86-64, Java 21, Python 3; không cần GPU)
gateway/tests/run.sh             # chạy gateway với reth thực, tắt tính năng khám phá peer (Docker, curl, jq, Python 3 cùng các gói trong demo/requirements.txt)
tests/guest-repro.sh             # bản dựng guest chạy trong một thư mục cố định, vì vậy thư mục nguồn không làm thay đổi ELF (dùng công cụ ZisK thay thế; cùng bước kiểm tra này trên ZisK thực đã đạt vào ngày 2026-10-04, xem guest/README.md)
tests/demo_static.sh             # các phiên bản ghim, công tắc giả mạo và ghi đè genesis của bản demo, cùng kết quả đã ghi lại (không cần GPU)
tests/demo_explorer_static.sh    # các image của explorer được ghim phiên bản và những gì được cung cấp cho container (không cần Docker)
(cd explorer && npm ci && npm test)  # các bài kiểm tra của explorer, chạy với đối tượng giả (Node 22.18+; CI sử dụng EXPLORER_NODE_IMAGE trong PINS)
(cd guest/rules && cargo test)   # các quy tắc chuỗi và mã băm của chúng (cần Rust)
```

## Chạy thử mà không cần GPU

```sh
tests/demo_rehearsal.sh          # bản demo và explorer với bằng chứng thay thế (Linux x86-64, Docker, Java 21, Rust, Python 3.12+; không cần GPU)
```

Lệnh này chạy reth, Canton, gói Daml, tiêu chuẩn token và builder thực. Sidecar kiểm tra các phần của gateway dựa trên bằng chứng lưu trữ, trong khi một thành phần thay thế phản hồi cho lệnh gọi `verify` này. Buổi chạy thử không chứng minh một block hay xác minh bằng chứng zero-knowledge thực.

Lệnh này cũng kiểm tra explorer và faucet. Bước kiểm tra Verify của explorer phải từ chối bằng chứng thay thế. README của [bản demo](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) mô tả phạm vi kiểm tra của buổi chạy thử.

## Khởi động mạng cục bộ với GPU

Cài đặt ZisK bằng `prover/install.sh` trước khi khởi động mạng. Luôn khởi động reth thông qua trình chạy được cung cấp; `network/up.sh` sử dụng trình chạy này.

```sh
network/up.sh       # công cụ, bản dựng guest, reth, sidecar, prover, Canton, chuỗi
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # một block rỗng, được chứng minh và ghi vào chuỗi
network/down.sh
```

`up.sh` biên dịch guest và từ chối program key, gốc ZisK hoặc mã băm quy tắc khác với các giá trị đã ghi. Mạng có một synchronizer và ba participant. Các participant operator và confirmer mỗi bên chạy một sidecar. Participant có tên users lưu trữ các party kiểm thử và reader.

Bài kiểm tra khói ghi một block rỗng vào chuỗi, kiểm tra block đầu chuỗi và bản ghi block của reader, đồng thời kiểm tra reth đã đánh dấu block là cuối cùng. Trạng thái và log được lưu vào `state/`, hoặc `CZE_STATE_DIR` nếu được thiết lập.

## Chạy năm trường hợp demo trên GPU

Dùng một mạng cục bộ mới cho bản demo:

```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      # tùy chọn: tạo trước một block rỗng
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

Tập lệnh chuẩn bị tạo khóa kiểm thử và một genesis đã cấp vốn cho lần chạy này. Bản demo chạy block thiết lập, nạp tiền, thanh toán, rút tiền, từ chối phân bổ và từ chối bằng chứng bị giả mạo. Tập lệnh dừng nếu có bước kiểm tra thất bại và ghi kết quả vào `demo/results/`.

Đối với bản xuất mã nguồn không có `.git`, hãy đặt `CZE_SOURCE_COMMIT` thành mã băm đầy đủ của commit được dùng để xuất. Để bao gồm faucet, cần chuẩn bị genesis đã cấp vốn của faucet trước khi khởi động mạng; xem [Tự chạy trình khám phá](#run-the-explorer-yourself) bên dưới và hướng dẫn demo đầy đủ.

## Giữ nguyên chuỗi qua các lần khởi động lại

Một chuỗi được mọi người sử dụng phải có thể tồn tại sau sự cố hoặc lần khởi động lại. `up.sh` sẽ tạo chuỗi mới mỗi lần chạy, trừ khi bạn yêu cầu chế độ lưu bền:

```sh
CZE_PERSIST=1 network/up.sh     # lần khởi động đầu tiên: tạo chuỗi mới và giữ lại
network/down.sh                 # dừng mọi thứ và giữ lại dữ liệu
network/restart.sh              # sau khi khởi động lại: khôi phục chính chuỗi đó
network/down.sh --wipe          # dừng mọi thứ và xóa chuỗi vĩnh viễn
```

Canton lưu các nút của mình trong PostgreSQL tại 127.0.0.1, với mật khẩu được tạo trên máy và lưu vào tệp có quyền 0600. reth lưu dữ liệu trong `$CZE_STATE_DIR/reth-data` và ghi từng khối vào đĩa khi nhập khối đó. `restart.sh` không tạo gì cả: tập lệnh khởi động cơ sở dữ liệu, reth, các sidecar, prover và Canton dựa trên dữ liệu đã lưu, đồng thời đưa reth đến trạng thái mới nhất của Canton. Tập lệnh sẽ dừng nếu cơ sở dữ liệu được tạo bởi phiên bản Canton khác với phiên bản trong `PINS`. Hãy sao lưu cơ sở dữ liệu và `reth-data` cùng nhau khi mạng đã dừng. Hướng dẫn [về mạng](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) bao gồm mọi trường hợp.

## Chạy trên một participant hiện có

Ostia có thể chạy trên một participant Canton đã có sẵn, chẳng hạn như validator Splice trên Canton Network DevNet, thay vì trên mạng cục bộ. Đây là cách Ostia DevNet hoạt động. `up.sh` sau đó khởi động reth, prover và, nếu bạn yêu cầu, một sidecar, rồi thiết lập chuỗi trên participant đó. Tập lệnh không khởi động Canton và cũng không bootstrap gì cả.

Bạn cần:

* JSON Ledger API (v2) của participant, dưới dạng URL `https` hoặc URL `http` trên cùng máy.
* Một tệp token cho mỗi người dùng trong số bốn người dùng Ledger API: `ADMIN` (tải gói lên và tạo các party cùng người dùng, vì vậy chỉ `up.sh` và `setup.py` cần token này) và `OPERATOR`, `CONFIRMER` và `BUILDER` (các người dùng `setup.py` được tạo, `ostia-operator`, `ostia-confirmer` và `ostia-builder`). Mỗi token dùng HS256, có audience là `https://canton.network.global` và ID người dùng làm giá trị `sub`. Người vận hành bên tham gia sẽ tạo chúng. Ostia không bao giờ tạo, in hay lưu trữ token.
* Một sidecar mà bên tham gia có thể truy cập, còn những bên khác thì không.

Token có thời hạn ngắn, vì vậy hãy ghi đè từng token mới vào cùng một tệp. Bộ dựng sẽ đọc lại tệp mỗi khi được gọi. `setup.py` và `propose.py` chỉ đọc mỗi token một lần, vì vậy hãy khởi chạy chúng bằng token mới.

Trước tiên, hãy cung cấp cho bên tham gia dòng cấu hình cần thiết dưới dạng một biến `ADDITIONAL_CONFIG` bổ sung của container, rồi khởi động lại bên tham gia:

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

Với `validate-on-startup` được đặt thành false, bên tham gia vẫn khởi động được khi sidecar ngừng hoạt động; khi đó, bước kiểm tra của một khối sẽ thất bại và không có khối nào được ghi nhận. Sau đó, khởi động chuỗi:

```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` là bắt buộc ở đây, vì chuỗi hoạt động trên bên tham gia và reth cũng cần giữ lại các khối của nó. Nếu sidecar chạy trên một máy khác, hãy khởi động sidecar tại đó bằng lệnh `network/external/sidecar.sh start <sidecar address>:8085` (địa chỉ mà bên tham gia dùng để truy cập sidecar, không phải địa chỉ công khai) rồi chạy `up.sh` mà không có `CZE_SIDECAR_LISTEN`. `up.sh` lệnh này sẽ dựng guest, khởi chạy reth và prover, đồng thời chạy `external/setup.py`, tập lệnh này tải gói lên, phân bổ các bên, tạo người dùng chỉ có quyền tương ứng với vai trò của họ và đề xuất chuỗi. Có thể chạy tập lệnh này hai lần mà không gây hại. `restart.sh` khởi động lại chuỗi và chỉ cần token của bộ dựng. `down.sh --wipe` không tác động đến bên tham gia: các hợp đồng của chuỗi vẫn ở đó cho đến khi người vận hành bên tham gia xóa chúng.

Có ba quy tắc áp dụng cho chế độ này:

* **Không bao giờ để Ledger API lộ ra bên ngoài.** API này có thể hoạt động với tư cách mọi bên mà bên tham gia lưu trữ. Hãy giới hạn API ở địa chỉ riêng của máy hoặc đặt sau proxy có kiểm tra bên gọi.
* **Đặt quyền cho các tệp token là 0600**, và không lưu chúng trên máy dùng chung.
* **Người vận hành bên tham gia có thể thấy mọi thứ.** Một bên tham gia lưu trữ mọi bên Ostia, vì vậy người vận hành có thể đọc mọi hợp đồng và hành động thay mặt cho mọi bên, bao gồm cả quyền lưu ký của cổng kết nối. Sidecar duy nhất của bên tham gia này là confirmer duy nhất. Trên Ostia DevNet, người vận hành đó là Rome: Rome chạy bên tham gia và trình xác thực Canton DevNet của chính mình.

## Chạy bộ dựng liên tục

`builder.py once` tạo một khối. `builder.py run` tiếp tục tạo các khối:

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

Lệnh này đọc cùng các [thiết lập](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) như `once`. Với chiến lược mặc định, `on_demand`, trình này tạo một khối mỗi khi có giao dịch đủ điều kiện đang chờ, mặc định mỗi lần chỉ có một khối đang được xử lý (`--max-in-flight` sẽ tăng giới hạn này). Chuỗi không hoạt động sẽ không tạo khối nào, trừ khi `--heartbeat-seconds N` yêu cầu tạo một khối rỗng sau N giây không có khối nào; mặc định không bật heartbeat. Sau hai khối liên tiếp bị từ chối, trình tạo nghi ngờ có giao dịch gây lỗi và tạm loại giao dịch đó trong một khoảng thời gian.

Mỗi lần chỉ chạy một trình tạo; `run` và `once` đều khóa để ngăn chạy nếu đã có tiến trình khác giữ khóa. Tín hiệu dừng sẽ hoàn tất khối đang xử lý rồi thoát. Chạy trình tạo dưới một trình quản lý dịch vụ có khả năng khởi động lại tiến trình, với thời gian chờ dừng dài hơn tổng thời gian tạo bằng chứng và nhận phản hồi từ Canton. Có thể khởi động lại an toàn bất cứ lúc nào: lần khởi động tiếp theo sẽ quay lại trạng thái mới nhất của Canton và gửi lại cho reth các giao dịch trong khối bị dừng giữa chừng. Trình tạo ghi `status.json` và nhật ký vào thư mục làm việc; explorer đọc cả hai.

## Tự chạy explorer

Explorer chạy dưới dạng một container bên cạnh chuỗi mà nó hiển thị, trên máy Linux có Docker. Nó có PostgreSQL riêng, được khởi động bằng `network/explorer-db.sh`; bộ lập chỉ mục điền dữ liệu vào cơ sở dữ liệu từ các bản ghi của Canton. Khoản tiền cấp cho faucet phải có trong genesis trước khi mạng khởi động, vì vậy cần chạy `setup` trước:

```sh
explorer/run.sh setup           # tạo khóa cho faucet và genesis có sẵn tiền
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # rồi mở http://127.0.0.1:8088
explorer/run.sh stop
```

`start` khởi động cơ sở dữ liệu, áp dụng các migration và chạy bộ lập chỉ mục trong container riêng, sau đó khởi động explorer. Nếu không có khóa faucet thì faucet sẽ tắt. Giao dịch chi trả từ faucet được gửi đến reth, vì vậy chỉ hoàn tất khi trình tạo chạy. Khởi động mạng hoặc explorer không khởi động trình tạo. Hãy chạy trình tạo một lần trước khi chạy `explorer/run.sh start`, hoặc chạy lại `start` sau lần chạy trình tạo đầu tiên; cho đến lúc đó, explorer chưa có thư mục làm việc của trình tạo và trạng thái vòng đời khối vẫn để trống. Trên mạng được tạo mà không có `CZE_PERSIST`, `stop` cũng xóa cơ sở dữ liệu của explorer, bao gồm các yêu cầu từ faucet và mã nguồn hợp đồng đã xác minh. Mạng có lưu trữ bền vững sẽ giữ lại cơ sở dữ liệu.

Lệnh `explorer/run.sh start` mặc định tắt tính năng xác minh hợp đồng, trừ khi bạn đặt `EXPLORER_VERIFIER=1` (cùng với `SOLC_LIST_URL`); đồng thời không bật `/rpc` và các lệnh gọi Read của hợp đồng, trừ khi bạn đặt `PUBLIC_RPC=1`. Các tùy chọn được liệt kê trong phần đầu của [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

Trên mạng cục bộ được cung cấp, Ledger API không yêu cầu đăng nhập. Explorer chỉ đọc với tư cách bên đọc, nhưng bất kỳ ai có thể truy cập participant đó cũng có thể đọc dữ liệu của các bên khác; vì vậy, tuyệt đối không gán địa chỉ công khai cho container tại đó. Trên participant hiện có, hãy cung cấp cho explorer tệp token quyền 0600 dành cho người dùng bên đọc (`LEDGER_TOKEN_FILE`), `LEDGER_URL` của participant và `READER_PARTY`. Bộ chứa vẫn lắng nghe trên 127.0.0.1; để dùng địa chỉ công khai, bạn cần tự thiết lập proxy. Hướng dẫn [trình khám phá](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) có đầy đủ mọi thiết lập.

## Tải bộ công cụ với một tổ hợp thực tế

`load/mixed` chứa bộ công cụ dùng cho đợt chạy một giờ trên [Measurements](https://docs.rome.builders/vi/canton-zk-evm/measurements.md). Bộ công cụ này triển khai nhiều loại token, một DEX, một token có cấp quyền và một hợp đồng chuyển khoản riêng tư trên một chuỗi, sau đó gửi lưu lượng hỗn hợp từ 200 ví. Tệp [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) có các bước hướng dẫn. Bạn cần Docker và một tài khoản có khoảng 12.000 tROME, cùng cấu hình mặc định của bộ công cụ. Trên chuỗi của riêng bạn, hãy cấp tiền cho tài khoản trong genesis. Vòi DevNet không thể cung cấp nhiều đến vậy.


---

# 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/vi/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.
