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

# Führe dein eigenes Ostia aus

Führen Sie die Prüfungen aus, die Übung ohne GPU, die lokale Demo auf einer GPU, eine Chain, die Neustarts übersteht, und Ostia auf einem bestehenden Canton-Teilnehmer.

Standardmäßig starten die bereitgestellten Skripte ein lokales Testnetzwerk. Canton speichert seinen Zustand im Arbeitsspeicher. Daher wird dieser Zustand bei jedem Neustart verworfen und ein neues Netzwerk erstellt. Zwei weitere Modi behalten eine Chain bei: der persistente Modus (`CZE_PERSIST=1`) und Ostia auf einem Canton-Teilnehmer, den Sie bereits haben – so läuft das Ostia DevNet. Die GPU-Demo erzeugt echte Beweise für Blöcke. Bei der Probe kommt ein Ersatzbeweis zum Einsatz; sie benötigt keine GPU.

Diese Seite beschreibt Release `v0.1.0`. Lesen Sie den vollständigen [Netzwerkleitfaden](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) und den [Demoleitfaden](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md). Führen Sie die folgenden Befehle im Stammverzeichnis des Repositorys `canton-zk-evm` aus.

## Voraussetzungen

| Aufgabe                  | Voraussetzungen                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Repository-Prüfungen     | Docker, `bash`, `curl`, `jq`, `openssl` und Python 3. Für Rust-Tests wird `rust-toolchain.toml`.                                 |
| Canton-Integrationstests | Linux x86-64, Java 21 und Netzwerkzugriff.                                                                                       |
| Demoprobe                | Linux x86-64, Docker, Java 21, Rust und Python 3.12 oder neuer.                                                                  |
| Explorer-Tests           | Node 22.18 oder neuer.                                                                                                           |
| GPU-Netzwerk und -Demo   | Linux x86-64, eine NVIDIA-GPU mit installiertem Treiber, Docker, Rust, Python 3.12 oder neuer, `jq`, `curl`, `openssl` und ZisK. |

Die [README des Repositorys](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) führt die Voraussetzungen für die Tests auf. Das GPU-Installationsprogramm verwendet `sudo` und `apt` unter Debian oder Ubuntu und benötigt etwa 100 GB freien Speicherplatz. Es installiert Systempakete und ändert die Limits für gesperrten Arbeitsspeicher. Das Tool zum Abrufen der Netzwerk-Tools installiert Java 21, falls es fehlt. Informationen zur getesteten Hardware finden Sie unter [Ostia-Prover-Host](https://docs.rome.builders/de/canton-zk-evm/prover-host.md) ; der erforderliche Mindestspeicher der GPU wurde nicht ermittelt.

## Tests ausführen

Beginnen Sie mit den Schnellprüfungen aus [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # Pins, Genesis und Lizenzzeilen stimmen überein
tests/refuses_missing_flag.sh    # der reth-Start verweigert ein fehlendes oder falsches Flag
tests/fixtures.sh                # der aufgezeichnete Beweis ist konsistent
gateway/build.sh --check         # der eingecheckte Gateway-Code entspricht dem, woraus Gateway.sol kompiliert wird (Docker)
```

In der README des Repositorys stehen außerdem diese Prüfungen. Sie benötigen keine GPU:

```sh
tests/udp_control.sh             # die UDP-Prüfung schlägt in einem Container mit UDP-Listener fehl (kein reth)
tests/discovery.sh               # startet den festgelegten reth, prüft, dass er keine Peers hat, und stoppt ihn
tests/network_static.sh          # reth ausschließlich über launch.sh, die Canton-Konfiguration und das protokollierte Smoke-Testergebnis
tests/network_checks.sh          # Prüfung der Compiler-Version, die ID des DAR und der Stopp bei einem anderen programVK (keine GPU)
tests/canton_network.sh          # das festgelegte Canton, das echte Daml-Paket und ein Advance (Linux x86-64, Java 21, Python 3; keine GPU)
gateway/tests/run.sh             # das Gateway mit einem echten reth, gestartet mit deaktivierter Peer-Erkennung (Docker, curl, jq, Python 3 mit den Paketen aus demo/requirements.txt)
tests/guest-repro.sh             # der Guest-Build läuft in einem festen Ordner, damit der Quellordner das ELF nicht verändert (Ersatzprogramme für die ZisK-Tools; dieselbe Prüfung mit echtem ZisK war am 2026-10-04 erfolgreich, siehe guest/README.md)
tests/demo_static.sh             # die Versionsfixierungen, der Manipulationsschalter und die Genesis-Überschreibung der Demo sowie ihre protokollierten Ergebnisse (keine GPU)
tests/demo_explorer_static.sh    # die Images des Explorers sind versionsfixiert und prüft, was dessen Container übergeben wird (kein Docker)
(cd explorer && npm ci && npm test)  # die Tests des Explorers mit Fakes (Node 22.18+; CI verwendet EXPLORER_NODE_IMAGE in PINS)
(cd guest/rules && cargo test)   # die Chain-Regeln und ihr Hash (Rust erforderlich)
```

## Probelauf ohne GPU

```sh
tests/demo_rehearsal.sh          # die Demo und der Explorer mit einem Ersatz-Proof (Linux x86-64, Docker, Java 21, Rust, Python 3.12+; keine GPU)
```

Hier werden der echte reth, Canton, das Daml-Paket, der Token-Standard und der Builder ausgeführt. Der Sidecar prüft die Abläufe des Gateways anhand von Speicherbeweisen, während ein Ersatzprogramm den Proof-Aufruf `verify` beantwortet. Beim Probelauf wird weder ein Block bewiesen noch ein echter Zero-Knowledge-Proof verifiziert.

Außerdem werden der Explorer und der Faucet geprüft. Die Verify-Prüfung des Explorers muss den Ersatz-Proof zurückweisen. Die [README der Demo](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) beschreibt, was der Probelauf abdeckt.

## Lokales Netzwerk mit GPU starten

Installieren Sie ZisK mit `prover/install.sh` bevor Sie das Netzwerk starten. Starten Sie reth immer über den bereitgestellten Launcher; `network/up.sh` verwendet ihn.

```sh
network/up.sh       # Tools, Guest-Build, reth, Sidecars, Prover, Canton, die Chain
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # ein leerer Block, bewiesen und committed
network/down.sh
```

`up.sh` baut den Guest und weist einen Programmschlüssel, eine ZisK-Root oder einen Regel-Hash zurück, der von den protokollierten Werten abweicht. Das Netzwerk hat einen Synchronizer und drei Teilnehmer. Die Teilnehmer operator und confirmer führen jeweils einen Sidecar aus. Der Teilnehmer namens users hostet die Testparteien und den Reader.

Der Smoke-Test committed einen leeren Block, prüft den Head der Chain und den Blockeintrag des Readers und stellt sicher, dass reth ihn als final markiert hat. Zustand und Logs werden in `state/`oder, falls gesetzt, in `CZE_STATE_DIR` gespeichert.

## Die fünf Demofälle mit GPU ausführen

Verwenden Sie für die Demo ein neues lokales Netzwerk:

```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      # optional: zuerst einen leeren Block
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

Das Vorbereitungsskript erstellt Testschlüssel und eine vorfinanzierte Genesis-Datei für den Lauf. Die Demo führt ihren Setup-Block, eine Einzahlung, eine Zahlung, eine Auszahlung, die Ablehnung einer Zuweisung und die Ablehnung eines manipulierten Proofs aus. Das Skript bricht bei einer fehlgeschlagenen Prüfung ab und schreibt die Ergebnisse nach `demo/results/`.

Für einen Quellcode-Export ohne `.git`, setzen Sie `CZE_SOURCE_COMMIT` auf den vollständigen Hash des für den Export verwendeten Commits. Wenn Sie den Faucet einbeziehen möchten, muss dessen vorfinanzierte Genesis-Datei vor dem Start des Netzwerks vorbereitet werden; siehe [Führen Sie den Explorer selbst aus](#run-the-explorer-yourself) weiter unten und im vollständigen Demo-Leitfaden.

## Die Chain über Neustarts hinweg beibehalten

Eine Chain, die genutzt wird, muss einen Absturz oder Neustart überstehen. `up.sh` erstellt bei jedem Aufruf eine neue Chain, sofern Sie nicht den persistenten Modus aktivieren:

```sh
CZE_PERSIST=1 network/up.sh     # beim ersten Start: eine neue Chain, die beibehalten wird
network/down.sh                 # stoppt alles und behält die Daten bei
network/restart.sh              # nach einem Neustart: dieselbe Chain wird wiederhergestellt
network/down.sh --wipe          # stoppt alles und entfernt die Chain dauerhaft
```

Canton speichert seine Knoten in PostgreSQL auf 127.0.0.1; das auf dem Rechner erzeugte Passwort wird in einer Datei mit Modus 0600 abgelegt. reth speichert seine Daten unter `$CZE_STATE_DIR/reth-data` und schreibt jeden Block während des Imports auf die Festplatte. `restart.sh` erstellt nichts: Es startet die Datenbank, reth, die Sidecars, den Prover und Canton mit den gespeicherten Daten und bringt reth auf den Head von Canton. Es wird abgebrochen, wenn die Datenbanken mit einer anderen Canton-Version als der in `PINS`erstellt wurden. Sichern Sie die Datenbanken und `reth-data` gemeinsam und bei gestopptem Netzwerk. Der [Netzwerkleitfaden](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) beschreibt alle Fälle.

## Auf einem vorhandenen Participant ausführen

Ostia kann statt im lokalen Netzwerk auf einem bereits vorhandenen Canton-Participant ausgeführt werden, etwa auf dem Participant eines Splice-Validators im Canton Network DevNet. So wird Ostia DevNet betrieben. `up.sh` startet dann reth, den Prover und auf Wunsch ein Sidecar und richtet die Chain auf diesem Participant ein. Canton wird nicht gestartet und es wird kein Bootstrap durchgeführt.

Sie benötigen:

* Die JSON Ledger API (v2) des Participants, als `https` -URL oder als `http` -URL auf demselben Rechner.
* Eine Token-Datei für jeden der vier Ledger-API-Benutzer: `ADMIN` (lädt das Paket hoch und erstellt die Parteien und Benutzer, daher benötigen nur `up.sh` und `setup.py` es) sowie `OPERATOR`, `CONFIRMER` und `BUILDER` (die Benutzer `setup.py` erstellt: `ostia-operator`, `ostia-confirmer` und `ostia-builder`). Jedes Token verwendet HS256 mit der Audience `https://canton.network.global` und der ID des Benutzers als `sub`. Wer den Participant betreibt, erstellt sie. Ostia erstellt, druckt oder speichert niemals ein Token.
* Ein Sidecar, das der Participant erreichen kann und sonst niemand.

Tokens sind kurzlebig. Schreiben Sie daher jedes neue Token direkt in dieselbe Datei. Der Builder liest seine Datei bei jedem Aufruf erneut ein. `setup.py` und `propose.py` lesen jedes Token nur einmal ein. Starten Sie sie daher mit frischen Tokens.

Geben Sie dem Participant zunächst die benötigte Zeile als weitere `ADDITIONAL_CONFIG` -Variable seines Containers und starten Sie ihn neu:

```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 }
```

Mit `validate-on-startup` auf false startet der Participant auch dann, wenn das Sidecar nicht verfügbar ist. Die Prüfung eines Blocks schlägt dann fehl, und es wird kein Block übernommen. Starten Sie anschließend die Chain:

```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` ist hier erforderlich, weil die Chain auf dem Participant verbleibt und reth seine Blöcke ebenfalls behalten muss. Wenn das Sidecar auf einem anderen Rechner läuft, starten Sie es dort mit `network/external/sidecar.sh start <sidecar address>:8085` (unter der Adresse, über die der Participant es erreicht, nicht unter einer öffentlichen Adresse) und führen Sie `up.sh` ohne `CZE_SIDECAR_LISTEN`. `up.sh` erstellt den Guest, startet reth und den Prover und führt `external/setup.py`aus. Das Skript lädt das Paket hoch, weist die Parteien zu, erstellt Benutzer mit ausschließlich den Berechtigungen ihrer jeweiligen Rollen und schlägt die Chain vor. Es kann gefahrlos zweimal ausgeführt werden. `restart.sh` bringt die Chain wieder hoch und benötigt nur das Token des Builders. `down.sh --wipe` greift nicht auf den Participant zu: Die Verträge der Chain bleiben dort, bis sein Betreiber sie entfernt.

Für diesen Modus gelten drei Regeln:

* **Machen Sie die Ledger API niemals öffentlich zugänglich.** Über sie kann jede Partei gesteuert werden, die auf dem Participant gehostet wird. Beschränken Sie den Zugriff auf die lokale Adresse des Rechners oder schützen Sie ihn mit einem Proxy, der die Aufrufer überprüft.
* **Setzen Sie für Token-Dateien den Modus 0600**und speichern Sie sie nicht auf gemeinsam genutzten Rechnern.
* **Der Betreiber des Participants kann alles sehen.** Ein Participant hostet alle Ostia-Parteien. Daher kann der Betreiber sämtliche Verträge lesen und für jede Partei handeln, einschließlich der Verwahrung durch das Gateway. Das einzige Sidecar ist zugleich der einzige Confirmer. Im Ostia DevNet ist dieser Betreiber Rom: Dort laufen der Participant und Roms eigener Canton-DevNet-Validator.

## Builder kontinuierlich ausführen

`builder.py once` erstellt einen Block. `builder.py run` erstellt fortlaufend weitere Blöcke:

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

Es liest dieselben [Einstellungen](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) wie `once`. Bei der standardmäßigen Strategie `on_demand` wird ein Block erstellt, sobald auszuführende Transaktionen anstehen. Standardmäßig ist jeweils nur ein Block gleichzeitig in Bearbeitung (`--max-in-flight`  erhöht diesen Wert). Auf einer ruhigen Chain werden keine Blöcke erstellt, außer `--heartbeat-seconds N`  nach N Sekunden ohne Block einen leeren Block anfordert; standardmäßig gibt es keinen Heartbeat. Nach zwei aufeinanderfolgenden abgelehnten Blöcken vermutet der Builder eine Transaktion als Ursache und lässt sie während einer Abkühlphase aus.

Es läuft immer nur ein Builder gleichzeitig; `run` und `once` sichern sich eine Sperre und verweigern den Start, wenn ein anderer Prozess sie hält. Bei einem Stoppsignal wird der laufende Block fertiggestellt und der Prozess beendet. Führen Sie den Builder unter einem Dienstmanager aus, der ihn neu startet, und legen Sie ein Stop-Timeout fest, das länger ist als die zusammengefasste Dauer von Proof und Cantons Antwort. Ein Neustart ist jederzeit sicher: Beim nächsten Start springt der Builder zurück zum Head von Canton und sendet die Transaktionen des abgeschnittenen Blocks erneut an reth. Der Builder schreibt `status.json` und ein Journal in seinen Arbeitsordner; der Explorer liest beide.

## Explorer selbst ausführen

Der Explorer läuft als Container neben der Chain, die er anzeigt, auf einem Linux-Rechner mit Docker. Er verfügt über eine eigene PostgreSQL-Datenbank, die von `network/explorer-db.sh`gestartet wird. Der Indexer befüllt sie mit Cantons Datensätzen. Die Finanzierung des Faucets muss bereits vor dem Netzwerkstart in der Genesis enthalten sein. Daher muss zuerst `setup` ausgeführt werden:

```sh
explorer/run.sh setup           # erstellt den Schlüssel des Faucets und eine finanzierte Genesis
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # anschließend http://127.0.0.1:8088 öffnen
explorer/run.sh stop
```

`start` startet die Datenbank, wendet die Migrationen an und startet den Indexer in einem eigenen Container; anschließend wird der Explorer gestartet. Wenn kein Faucet-Schlüssel vorhanden ist, ist das Faucet deaktiviert. Eine Auszahlung des Faucets ist eine Transaktion an reth und wird daher erst final, wenn der Builder läuft. Beim Starten des Netzwerks oder des Explorers wird der Builder nicht gestartet. Führen Sie den Builder einmal aus, bevor Sie `explorer/run.sh start`ausführen, oder führen Sie `start` nach dem ersten Lauf des Builders erneut aus. Bis dahin hat der Explorer keinen Arbeitsordner des Builders, und der Blocklebenszyklus bleibt leer. In einem Netzwerk, das ohne `CZE_PERSIST`, `stop` löscht außerdem die Datenbank des Explorers samt Faucet-Anfragen und verifizierten Contract-Quellen. Bei einem persistenten Netzwerk bleibt sie erhalten.

Bei einem standardmäßigen `explorer/run.sh start` ist die Contract-Verifizierung deaktiviert, sofern Sie nicht `EXPLORER_VERIFIER=1`  (mit `SOLC_LIST_URL`) festlegen. Außerdem gibt es weder `/rpc` noch Contract-Read-Aufrufe, sofern Sie nicht `PUBLIC_RPC=1`festlegen. Die Einstellungen sind im Header von [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

aufgeführt. Im bereitgestellten lokalen Netzwerk erfordert die Ledger API keine Anmeldung. Der Explorer liest nur als Reader-Partei, aber jeder, der diesen Teilnehmer erreichen kann, kann auch dessen andere Parteien auslesen. Geben Sie dem Container daher dort niemals eine öffentliche Adresse. Bei einem bestehenden Teilnehmer stellen Sie dem Explorer eine Token-Datei im Modus 0600 für den Reader-Benutzer (`LEDGER_TOKEN_FILE`), die `LEDGER_URL` des Teilnehmers und die `READER_PARTY` . Der Container lauscht weiterhin auf 127.0.0.1; für eine öffentliche Adresse benötigen Sie einen eigenen Proxy. Der  [Explorer-Leitfaden](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) enthält alle Einstellungen.

## Laden Sie eine realistische Mischung

`load/mixed` enthält das Kit für den einstündigen Lauf unter [Messungen](https://docs.rome.builders/de/canton-zk-evm/measurements.md). Es stellt auf einer Chain Token verschiedener Arten, eine DEX, einen zugriffsbeschränkten Token und einen Vertrag für private Überweisungen bereit und sendet anschließend gemischten Traffic von 200 Wallets. Die [README-Datei](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) enthält die Schritte. Sie benötigen Docker und ein Konto mit etwa 12.000 tROME, wenn die mitgelieferte Konfiguration des Kits verwendet wird. Auf Ihrer eigenen Chain müssen Sie das Konto im Genesis-Block aufladen. Der DevNet-Faucet kann nicht so viel bereitstellen.


---

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