Einen Node betreiben

Dieser Leitfaden behandelt den Betrieb eines reinen Node-Deployments von QoreChain — ein Full- oder RPC-Node, der die Chain synchronisiert und Endpunkte für Integrationen bereitstellt, ohne Validator-Aufgaben. Er richtet sich an Börsen (CEX), Wallet-Backends, Indexer und Integratoren, die zuverlässigen Lese-/Schreibzugriff auf das Netzwerk benötigen, aber keine Blöcke signieren.

hinweis

Für Blockproduktion, Staking, Slashing und Pool-Klassifizierung siehe stattdessen Einen Validator betreiben. Ein reines Node-Deployment hält niemals einen Validator-Konsensschlüssel und erscheint niemals im aktiven Set.

warnung

Binaries, Genesis und Snapshots werden unter download.qore.host mit SHA-256-Prüfsummen veröffentlicht. Verifizieren Sie Prüfsummen immer vor dem Installieren oder Entpacken, und verifizieren Sie Einzahlungen ausschließlich gegen Ihren eigenen, synchronisierten Node.

Source of truth: das Live-Manifest

Das aktuelle Binary, Genesis, Peers, Seeds und ein State-Sync-Trust-Point werden als JSON-Manifest veröffentlicht, das live aktualisiert wird — hinterlegen Sie in Ihren Installationsskripten keine fest codierte Binary-Version, Prüfsumme oder Snapshot-Dateinamen, da diese veralten, sobald ein neues Release erscheint:

Mainnet: https://download.qore.host/mainnet/latest.json
Testnet: https://download.qore.host/testnet/latest.json

Die Felder des Manifests umfassen binary (URL + sha256), genesis (URL + sha256 + sizeBytes), peers, seeds, p2pPort, stateSync (ein stündlich aktualisierter Trust-Point) und minCompatible. Die Installations- und Beitrittsschritte unten rufen dieses Manifest ab und verwenden dessen aktuelle Werte.

v3.2.0 oder höher für einen frisch beitretenden Node erforderlich

Ein Node, der ab Genesis synchronisiert oder aus einem Snapshot repliziert, durchläuft mehrere Governance-Upgrades (zum Beispiel die Emissionsobergrenze v3.1.94 bei Höhe 2.122.074 und das Upgrade v3.2.0 bei Höhe 2.981.742). Installieren Sie daher immer das Binary, auf das das Manifest verweist: Es enthält jeden Upgrade-Handler. Ein frischer Mainnet-Node benötigt v3.2.0 oder höher: minCompatible im Manifest ist 3.2.0, das älteste Release, das der Chain noch folgt, und version (derzeit 3.2.1) ist die empfohlene, ein node-lokales Release ohne Upgrade-Höhe. Das Manifest wird bewusst gestaffelt befördert (zuerst Testnet, danach Mainnet nach einer Einlaufphase). Prüfen Sie daher sein Feld "version" gegen minCompatible, bevor Sie binary.url vertrauen. Im Testnet entspricht minCompatible der version (derzeit 3.2.2).

Ab v3.2.1 sind zwei Einstellungen wichtig: Halten Sie die Systemuhr per NTP synchronisiert (der Node stoppt, wenn seine Uhr um mehr als 60 Sekunden abweicht), und setzen Sie evm-chain-id in app.toml (siehe Node-Limits).

Node vs. Validator

Aspekt	Reiner Node (dieser Leitfaden)	Validator
Konsensschlüssel	Keiner	ed25519-Konsensschlüssel (muss gesichert werden)
Blockproduktion	Nein	Ja — schlägt Blöcke vor und signiert sie
Staking / Slashing	Nicht anwendbar	Selbstdelegation, Slashing-Risiko
Hauptzweck	RPC/REST/gRPC/EVM (und schreibgeschütztes SVM) für Integrationen bereitstellen	Netzwerk sichern (Staking-Rewards fallen an)
Öffentliche Erreichbarkeit	RPC/EVM-Endpunkte typischerweise exponiert	Validator hinter Sentry-Nodes verborgen

Zielnetzwerke

Netzwerk	Chain-ID	EVM-Chain-ID	Hinweise
Mainnet	`qorechain-vladi`	`9801` (hex `0x2649`)	Primär — live seit 29. Juni 2026
Testnet	`qorechain-diana`	`9800`	Integrationen zuerst hier erproben

Setzen Sie in diesem Leitfaden durchgehend die passende --chain-id für Ihr Zielnetzwerk ein. Die Beispiele verwenden standardmäßig das Mainnet.

Empfohlene Hardware

Profil	CPU	RAM	Festplatte (NVMe-SSD)	Netzwerk
Geprunter RPC-Node	4 Kerne	16 GB	500 GB+	100 Mbps+
Full-/Archive-Node	8 Kerne	32 GB	2 TB+ (wächst mit der Zeit)	1 Gbps
Börsen-Integration	8 Kerne	32 GB	2 TB+ mit Reserve	1 Gbps

Eine NVMe-SSD wird dringend empfohlen — der Chain-State und die EVM-/SVM-Stores sind I/O-intensiv. Archive-Nodes (kein Pruning, vollständige Tx-Indexierung) wachsen kontinuierlich; stellen Sie Speicherplatz mit Reserve und Monitoring bereit.

Deployment

Docker Compose

Ein reines Node-Deployment mit Docker Compose. Es gibt derzeit noch kein öffentlich veröffentlichtes qorechaind-Image zum Herunterladen. Das Dockerfile im öffentlichen Repository baut das Community-Binary (keine Post-Quanten-Bibliothek, Stub-Keeper): Das eignet sich für die lokale Entwicklung, kann aber weder dem Mainnet noch dem Testnet folgen. Bauen Sie für einen Netzwerk-Node ein eigenes Image aus dem in latest.json genannten Release-Archiv, taggen Sie es auf die Release-Version (v3.2.1 im Mainnet, v3.2.2 im Testnet) und mounten Sie dann ein persistentes Volume für die Chain-Daten:

# Fetch and verify the release archive (see "Joining the Network" below for the manifest steps)
curl -s https://download.qore.host/mainnet/latest.json -o latest.json
curl -fsSL "$(jq -r .binary.url latest.json)" -o qore.tgz
echo "$(jq -r .binary.sha256 latest.json)  qore.tgz" | sha256sum -c -
mkdir release && tar xzf qore.tgz -C release

cat > release/Dockerfile <<'EOF'
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates curl jq && rm -rf /var/lib/apt/lists/*
COPY qorechaind /usr/local/bin/qorechaind
COPY lib/ /opt/qorechain/lib/
ENV LD_LIBRARY_PATH=/opt/qorechain/lib
ENTRYPOINT ["qorechaind"]
EOF
docker build -t qorechain-node:v3.2.1 release/

Das Archiv enthält qorechaind und ein Verzeichnis lib/ mit den zugehörigen Shared Libraries (libqorepqc.so, libqoresvm.so, libwasmvm.x86_64.so); das obige Image ist, wie das Release-Archiv, nur für linux/amd64.

# docker-compose.yml
services:
  qorechain-node:
    image: qorechain-node:v3.2.1
    container_name: qorechain-node
    restart: unless-stopped
    command: ["start", "--home", "/root/.qorechaind"]
    volumes:
      - qorechain-data:/root/.qorechaind
    ports:
      - "26657:26657"   # RPC
      - "26656:26656"   # P2P
      - "1317:1317"     # REST
      - "9090:9090"     # gRPC
      - "8545:8545"     # EVM JSON-RPC
      - "8546:8546"     # EVM WebSocket
      - "8899:8899"     # SVM RPC (read-only: SVM transactions are disabled)
      - "26660:26660"   # Prometheus

volumes:
  qorechain-data:

Initialisieren Sie das Datenverzeichnis einmalig (zum Beispiel docker compose run --rm qorechain-node init my-node --chain-id qorechain-vladi --home /root/.qorechaind; Genesis- und Peer-Konfiguration werden weiter unten behandelt) und starten Sie dann:

docker compose up -d
docker compose logs -f qorechain-node

systemd

Für eine Bare-Metal-Installation betreiben Sie qorechaind unter systemd:

# /etc/systemd/system/qorechaind.service
[Unit]
Description=QoreChain node
After=network-online.target
Wants=network-online.target

[Service]
User=qorechain
ExecStart=/usr/local/bin/qorechaind start --home /var/lib/qorechaind
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now qorechaind
sudo journalctl -u qorechaind -f

Dem Netzwerk beitreten

1. Initialisieren

qorechaind init my-node --chain-id qorechain-vladi

2. Manifest abrufen

curl -s https://download.qore.host/mainnet/latest.json -o latest.json
# testnet: https://download.qore.host/testnet/latest.json

Verwenden Sie diese Datei als Quelle für die Binary-, Genesis- und Peer-Werte in den folgenden Schritten — prüfen Sie jq -r .minCompatible latest.json und betreiben Sie mindestens dieses Release (das empfohlene ist jq -r .version latest.json).

3. Genesis herunterladen und verifizieren

GENESIS_URL=$(jq -r .genesis.url latest.json)
GENESIS_SHA256=$(jq -r .genesis.sha256 latest.json)

curl -fsSL "$GENESIS_URL" -o ~/.qorechaind/config/genesis.json
echo "${GENESIS_SHA256}  $HOME/.qorechaind/config/genesis.json" | sha256sum -c -

# Cross-verify against the genesis served live by the chain:
curl -s https://rpc.qore.host/genesis | jq '.result.genesis' > /tmp/genesis-live.json

4. Peers und die Gebührenuntergrenze konfigurieren

Lesen Sie die aktuellen Peers und Seeds aus dem Manifest, statt Node-IDs und Hosts fest zu codieren — diese rotieren:

PEERS=$(jq -r '.peers | join(",")' latest.json)
SEEDS=$(jq -r '.seeds | join(",")' latest.json)

Öffnen Sie ~/.qorechaind/config/config.toml und setzen Sie persistent_peers (und seeds) auf diese Werte:

persistent_peers = "<value of $PEERS>"
seeds = "<value of $SEEDS>"

Setzen Sie anschließend den minimalen Gaspreis in ~/.qorechaind/config/app.toml (Netzwerk-Gebührenuntergrenze: 0.1uqor):

minimum-gas-prices = "0.1uqor"

qorechaind init <moniker> --chain-id qorechain-vladi schreibt außerdem die EVM-Chain-ID des Netzwerks in app.toml (siehe Node-Limits); prüfen Sie sie bei einem Home-Verzeichnis, das vor langer Zeit initialisiert wurde.

5. Synchronisierung starten

qorechaind start --minimum-gas-prices=0.1uqor

Schneller Bootstrap

Die Synchronisierung ab Genesis kann sehr lange dauern. Verwenden Sie für Integrationen State Sync oder einen Snapshot für einen schnellen Kaltstart.

State Sync

State Sync lädt einen aktuellen Snapshot des Anwendungszustands von vertrauenswürdigen RPC-Servern, anstatt jeden Block erneut abzuspielen. Konfigurieren Sie den Abschnitt [statesync] in config.toml:

[statesync]
enable = true
rpc_servers = "https://rpc.qore.host:443,https://rpc.qore.host:443"
trust_height = <TRUSTED_BLOCK_HEIGHT>
trust_hash = "<TRUSTED_BLOCK_HASH>"
trust_period = "168h0m0s"

Entnehmen Sie trust_height / trust_hash dem Feld stateSync des Manifests — es wird stündlich aktualisiert und ist damit die bevorzugte Quelle:

TRUST_HEIGHT=$(jq -r .stateSync.trustHeight latest.json)
TRUST_HASH=$(jq -r .stateSync.trustHash latest.json)

Als Fallback/Alternative können Sie eine vertrauenswürdige Höhe und deren Hash selbst über den öffentlichen RPC ableiten:

curl -s https://rpc.qore.host/block | jq -r '.result.block.header.height, .result.block_id.hash'

Snapshot-Wiederherstellung

Alternativ laden Sie den veröffentlichten Chain-Daten-Snapshot herunter, verifizieren dessen Prüfsumme und entpacken ihn über Ihr Datenverzeichnis. Im Mainnet nennt das Objekt snapshot des Manifests die URL, die Blockhöhe (height), die Größe und die SHA-256-Prüfsumme (das Testnet-Manifest enthält derzeit nur die URL, verwenden Sie dort also State Sync). Lesen Sie snapshot.height, bevor Sie ihn verwenden: Der Mainnet-Snapshot ist ein einzelnes Archiv von etwa 27 GB, und ein alter bedeutet eine lange Aufholphase (der derzeit veröffentlichte Mainnet-Snapshot liegt vor den Upgrade-Höhen von v3.1.94 und v3.2.0, ein daraus wiederhergestellter Node muss sie also mit einem v3.2.x-Binary replizieren).

SNAP_URL=$(jq -r .snapshot.url latest.json)
SNAP_SHA256=$(jq -r .snapshot.sha256 latest.json)
curl -fsSL "$SNAP_URL" -o snapshot.tar.gz
echo "${SNAP_SHA256}  snapshot.tar.gz" | sha256sum -c -

tar xzf snapshot.tar.gz -C ~/.qorechaind/
qorechaind start --minimum-gas-prices=0.1uqor

hinweis

Die Felder snapshot.height und snapshot.ts des Manifests zeigen, wie aktuell das Archiv ist, und State Sync (oben) ist meist schneller als ein Download von 27 GB. Verifizieren Sie vor dem Entpacken immer die Prüfsumme, und verwenden Sie beim Replay aus einem Snapshot ein Node-Release, das jeden Upgrade-Handler enthält (siehe den Hinweis am Anfang dieser Seite).

Pruning und Indexierung

Stimmen Sie Pruning und Transaktionsindexierung auf Ihre Integration ab. Börsen, die eine vollständige Transaktionshistorie benötigen, sollten mit minimalem Pruning und aktiviertem Transaktionsindexer laufen.

Pruning (`app.toml`)

# Keep recent state only — smallest disk footprint
pruning = "default"

# Keep everything — required for archive / full historical queries
# pruning = "nothing"

`pruning`	Verhalten	Anwendungsfall
`default`	Behält aktuellen State, prunt den Rest	RPC-Node, Kontostands-/State-Abfragen
`nothing`	Behält den gesamten historischen State	Archive-Node, vollständige Historie
`custom`	Vom Betreiber definierte Keep-/Intervall-Werte	Feinabgestimmte Aufbewahrung

Node-Limits (`app.toml`)

Ab Node-Release v3.2.1 schreibt init einen Abschnitt [qorechain] mit drei node-lokalen Limits. Sie ändern nur, was dieser Node im Speicher hält und was er in die von ihm vorgeschlagenen Blöcke aufnimmt, niemals aber, was ein Block enthalten muss, um gültig zu sein:

[qorechain]
# Maximum number of Cosmos transactions held in the app-side mempool (default 5000).
# When full, a new transaction that pays more per gas evicts the lowest-paying one; otherwise it is refused.
cosmos-mempool-max-txs = 5000

# Time the node may spend selecting transactions for a proposal before it proposes what it has ("0s" disables the budget).
prepare-proposal-budget = "1s"

# Stop after this many candidates in a row that do not fit in the remaining block space (0 disables the cap).
prepare-proposal-max-skips = 64

init schreibt außerdem die EVM-Chain-ID des Netzwerks in die Einstellung evm-chain-id im Abschnitt [evm] von app.toml (9801 für --chain-id qorechain-vladi, 9800 für qorechain-diana). Ein Node, dessen app.toml einen anderen Wert enthält, startet zwar, protokolliert beim Start aber einen Fehler, und sein eigenes JSON-RPC (eth_chainId, Signieren gegen diesen Node) antwortet mit der falschen Chain-ID, bis Sie die Datei korrigieren; der Konsens ist davon nicht betroffen. Ältere Binaries schrieben unabhängig von --chain-id den Testnet-Wert (9800), daher sollte ein vor langer Zeit initialisierter Mainnet-Node diese Einstellung prüfen. Setzen Sie QORE_EVM_CHAIN_ID nicht auf einen anderen Wert als den des Netzwerks: Ein solcher Node verweigert den Start.

Transaktionsindexierung (`config.toml`)

[tx_index]
indexer = "kv"

Setzen Sie indexer = "kv" (oder einen umfangreicheren Indexer), damit Transaktionen per Hash und Event abfragbar sind — essenziell für Börsen, die Ein- und Auszahlungen abgleichen. Setzen Sie indexer = "null" nur, wenn Sie keine historischen Tx-Abfragen benötigen.

Endpunkte für Integrationen bereitstellen

Aktivieren und binden Sie in app.toml die API-Server, die Integratoren benötigen:

[api]
enable = true
address = "tcp://0.0.0.0:1317"

[grpc]
enable = true
address = "0.0.0.0:9090"

[json-rpc]
enable = true
address = "0.0.0.0:8545"
ws-address = "0.0.0.0:8546"
api = "eth,net,web3,txpool"

Die öffentlichen Endpunkte stellen die Namespaces eth_, net_, web3_ und txpool_ bereit. Der Namespace qor_ wird von keinem veröffentlichten Node-Build bereitgestellt, fügen Sie ihn daher nicht hinzu (siehe den Namespace qor_).

Und den RPC-Listener in config.toml:

[rpc]
laddr = "tcp://0.0.0.0:26657"

Endpunkt	Port	Verwendung für
RPC	`26657`	Broadcasting von Transaktionen, Abfragen von Blöcken/Status
REST	`1317`	HTTP-Abfragen des Chain-States
gRPC	`9090`	Programmatischer Zugriff mit hohem Durchsatz
EVM JSON-RPC	`8545`	Ethereum-kompatible Integrationen (Chain-ID `9801`)
EVM WS	`8546`	EVM-Event-Subscriptions
SVM RPC	`8899`	Solana-kompatible Lesezugriffe (SVM-Transaktionen sind deaktiviert)

warnung

Exponieren Sie RPC, EVM JSON-RPC oder gRPC niemals direkt ins öffentliche Internet ohne Reverse Proxy, Rate Limiting, Authentifizierung und Firewall. Binden Sie an 0.0.0.0 nur hinter einer kontrollierten Ingress-Schicht.

Health- und Sync-Monitoring

Sync-Status

curl -s localhost:26657/status | jq '.result.sync_info.catching_up'

true — synchronisiert noch.
false — vollständig synchronisiert und liefert den aktuellen State.

# Latest height and network
curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height, .result.node_info.network'

Das Feld network sollte qorechain-vladi (Mainnet) oder qorechain-diana (Testnet) melden.

Prometheus und Grafana

Der Node kann Prometheus-Metriken auf Port 26660 bereitstellen (setzen Sie prometheus = true im Abschnitt [instrumentation] von config.toml):

http://localhost:26660/metrics

Scrapen Sie diese mit einem beliebigen Prometheus-kompatiblen Collector. Wenn Sie den Docker-Compose-Monitoring-Stack betreiben, ist Grafana unter http://localhost:3001 erreichbar — legen Sie beim ersten Login eigene Zugangsdaten fest. Überwachen Sie Blockhöhen-Rückstand, Peer-Anzahl und Ressourcennutzung; alarmieren Sie, wenn catching_up dauerhaft true bleibt oder die Peer-Anzahl auf null fällt.

EVM-Endpunkt-Prüfung

curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# Expect "0x2649" (9801) on mainnet

Bewährte Betriebspraktiken

Pinnen Sie die Chain-Version. Betreiben Sie das vom Manifest empfohlene Release (v3.2.1 im Mainnet), verfolgen Sie offizielle Releases für koordinierte Upgrades und halten Sie die Systemuhr per NTP synchronisiert.
Betreiben Sie redundante Nodes. Betreiben Sie mindestens zwei Nodes hinter einem Load Balancer, damit ein einzelner Neustart oder Resync den Integrationsverkehr nicht unterbricht.
Verifizieren Sie Genesis und Snapshots. Validieren Sie die Genesis-SHA-256 und jede Snapshot-Prüfsumme immer gegen das offizielle Release, bevor Sie starten.
Schützen Sie öffentliche Endpunkte. Stellen Sie RPC/EVM/gRPC einen Reverse Proxy, Rate Limiting und eine Firewall voran. Exponieren Sie niemals unauthentifiziertes Schreib-RPC ins Internet.
Passen Sie das Pruning an den Bedarf an. Verwenden Sie pruning = "nothing" plus tx_index = "kv" für Börsen, die die vollständige Ein-/Auszahlungshistorie abgleichen; verwenden Sie default für leichtgewichtige Abfragen.
Überwachen Sie die Synchronisierung kontinuierlich. Alarmieren Sie bei Blockhöhen-Rückstand, null Peers und einem Node, der in catching_up feststeckt.

Ein reines Node-Deployment signiert nie. Transaktionen, die Ihre Integration darüber sendet, müssen bereits die hybride Post-Quanten-Signatur tragen (und für die EVM-Lane benötigt der Absender einen registrierten Schlüssel und ein offenes Autorisierungsfenster); siehe Börsen-Integration und Post-Quanten-Signierung.

Um das Netzwerk ohne den Betrieb eines Full Nodes zu beobachten, siehe die Light-Node-Dokumentation.

Fehlerbehebung

Der Node stoppt mit einem Uhrenfehler

Ab Node-Release v3.2.1 stoppt die Konsens-Engine, wenn die Systemuhr um mehr als 60 Sekunden vom Netzwerk abweicht. Betreiben Sie einen NTP-Client (chrony oder systemd-timesyncd), prüfen Sie mit timedatectl status, dass die Uhr synchronisiert ist, und starten Sie den Node dann neu.

Ein bereits vor dem Upgrade angehaltener Node läuft nach einem Binary-Wechsel nicht weiter

Wenn Ihr Node bereits vor dem Upgrade seines Binaries angehalten hatte oder feststeckte, reicht es nicht aus, einfach das neue Binary einzusetzen und neu zu starten — der Node hat veraltete ABCI-Ergebnisse aus dem alten Lauf im Cache und führt den Block, der das Anhalten verursacht hat, nicht erneut aus. Setzen Sie explizit zurück, bevor Sie neu starten:

qorechaind rollback --home <HOME>
systemctl restart <unit>

Der Befehl lautet qorechaind rollback (ein Top-Level-Subcommand) — es gibt kein Subcommand comet rollback und keine --hard-Flag dafür.

Snapshot-Wiederherstellung landet in einer Crash-Loop wegen einer fehlenden `priv_validator_state.json`

Ein veröffentlichtes Archiv/Snapshot enthält nicht data/priv_validator_state.json, und der Node verweigert ohne diese Datei den Start. Falls sie nach einer Snapshot-Wiederherstellung fehlt, erstellen Sie sie — aber nur, wenn noch keine existiert. Überschreiben Sie niemals eine echte: Auf einem Validator ist diese Datei die Anti-Double-Signing-Sicherung, und ein Überschreiben riskiert ein Double-Sign.

echo '{"height":"0","round":0,"step":0}' > <HOME>/data/priv_validator_state.json

Nächste Schritte

Verbindung mit dem Mainnet — Mainnet-Genesis, Peers und Verbindungsdetails
Einen Validator betreiben — Blockproduktions-Aufgaben hinzufügen
Aus dem Quellcode bauen — Das Community-qorechaind-Binary für die Entwicklung bauen
Light Node — Leichtgewichtiger Client, der dem Netzwerk ohne Full Node folgt

Node vs. Validator​

Zielnetzwerke​

Empfohlene Hardware​

Deployment​

Docker Compose​

systemd​

Dem Netzwerk beitreten​

1. Initialisieren​

2. Manifest abrufen​

3. Genesis herunterladen und verifizieren​

4. Peers und die Gebührenuntergrenze konfigurieren​

5. Synchronisierung starten​

Schneller Bootstrap​

State Sync​

Snapshot-Wiederherstellung​

Pruning und Indexierung​

Pruning (app.toml)​

Node-Limits (app.toml)​

Transaktionsindexierung (config.toml)​

Endpunkte für Integrationen bereitstellen​

Health- und Sync-Monitoring​

Sync-Status​

Prometheus und Grafana​

EVM-Endpunkt-Prüfung​

Bewährte Betriebspraktiken​

Fehlerbehebung​

Der Node stoppt mit einem Uhrenfehler​

Ein bereits vor dem Upgrade angehaltener Node läuft nach einem Binary-Wechsel nicht weiter​

Snapshot-Wiederherstellung landet in einer Crash-Loop wegen einer fehlenden priv_validator_state.json​

Nächste Schritte​