Sari la conținutul principal

Rularea unui nod

Acest ghid acoperă rularea unei implementări QoreChain doar-nod — un nod complet sau RPC care sincronizează lanțul și expune endpoint-uri pentru integrare, fără atribuții de validator. Se adresează exchange-urilor (CEX), backend-urilor de portofel, indexatorilor și integratorilor care au nevoie de acces fiabil de citire/scriere la rețea, dar nu semnează blocuri.

notă

Pentru producția de blocuri, staking, slashing și clasificarea pool-urilor, consultați Rularea unui Validator. O implementare doar-nod nu deține niciodată o cheie de consens de validator și nu apare niciodată în setul activ.

avertisment

Binarele, genesis-ul și instantaneele (snapshots) sunt publicate la download.qore.host cu sume de control SHA-256. Verificați întotdeauna sumele de control înainte de a instala sau extrage, și verificați depozitele doar în raport cu propriul nod sincronizat.

Sursa de adevăr: manifestul live

Binarul curent, genesis-ul, peers, seeds și un punct de încredere pentru state-sync sunt publicate ca manifest JSON, actualizat live — nu codificați rigid o versiune de binar, o sumă de control sau un nume de fișier de instantaneu în scripturile de instalare, deoarece devin învechite imediat ce apare o versiune nouă:

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

Câmpurile manifestului includ binary (url + sha256), genesis (url + sha256 + sizeBytes), peers, seeds, p2pPort, stateSync (un punct de încredere actualizat orar) și minCompatible. Pașii de instalare și conectare de mai jos preiau acest manifest și folosesc valorile lui curente.

v3.2.0 sau mai nou necesar pentru un nod care se alătură de la zero

Un nod care se sincronizează de la genesis sau reface starea dintr-un instantaneu trece prin mai multe upgrade-uri de guvernanță (de exemplu plafonul de emisiune v3.1.94 la înălțimea 2.122.074 și upgrade-ul v3.2.0 la înălțimea 2.981.742), așa că instalați întotdeauna binarul indicat de manifest: acesta conține toate handler-ele de upgrade. Un nod nou de mainnet are nevoie de v3.2.0 sau mai nou: minCompatible din manifest este 3.2.0, cea mai veche versiune care încă urmează lanțul, iar version (în prezent 3.2.1) este cea recomandată, o versiune locală a nodului, fără înălțime de upgrade. Manifestul este promovat deliberat (mai întâi pe testnet, apoi pe mainnet după o perioadă de rodaj), așa că verificați câmpul său "version" în raport cu minCompatible înainte de a avea încredere în binary.url. Pe testnet, minCompatible este egal cu version (în prezent 3.2.2).

Două setări contează începând cu v3.2.1: mențineți ceasul sistemului sincronizat prin NTP (nodul se oprește dacă ceasul său are o abatere de mai mult de 60 de secunde) și setați evm-chain-id în app.toml (consultați Limitele nodului).

Nod vs Validator​

AspectDoar-nod (acest ghid)Validator
Cheie de consensNiciunaCheie de consens ed25519 (trebuie securizată)
Producție de blocuriNuDa — propune și semnează blocuri
Staking / slashingNu se aplicăAuto-delegare, risc de slashing
Scop principalServește RPC/REST/gRPC/EVM (și SVM doar-citire) pentru integrăriSecurizează rețeaua (se aplică recompense de staking)
Expunere publicăEndpoint-urile RPC/EVM sunt de obicei expuseValidatorul este ascuns în spatele nodurilor sentry

Rețele țintă​

RețeaChain IDChain ID EVMNote
Mainnetqorechain-vladi9801 (hex 0x2649)Principală — live din 29 iunie 2026
Testnetqorechain-diana9800Testați integrările aici mai întâi

Înlocuiți --chain-id-ul corespunzător pentru rețeaua țintă pe parcursul acestui ghid. Exemplele folosesc implicit mainnet.

Hardware recomandat​

ProfilCPURAMDisc (NVMe SSD)Rețea
Nod RPC cu pruning4 nuclee16 GB500 GB+100 Mbps+
Nod complet/arhivă8 nuclee32 GB2 TB+ (crește în timp)1 Gbps
Integrare de exchange8 nuclee32 GB2 TB+ cu marjă suplimentară1 Gbps

Un SSD NVMe este puternic recomandat — starea lanțului și magaziile EVM/SVM sunt intensive din punct de vedere I/O. Nodurile de arhivă (fără pruning, indexare completă a tranzacțiilor) cresc continuu; alocați spațiu pe disc cu marjă și monitorizare.

Implementare (Deployment)​

Docker Compose​

O implementare doar-nod cu Docker Compose. Nu există încă o imagine qorechaind publicată public de descărcat. Dockerfile-ul din repository-ul public construiește binarul community (fără bibliotecă post-cuantică, keepers de tip stub): este potrivit pentru dezvoltare locală, dar nu poate urmări mainnet-ul sau testnet-ul. Pentru un nod de rețea, construiți-vă propria imagine din arhiva de versiune indicată în latest.json, etichetați-o cu versiunea (v3.2.1 pe mainnet, v3.2.2 pe testnet), apoi montați un volum persistent pentru datele lanțului:

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

Arhiva conține qorechaind și un director lib/ cu bibliotecile sale partajate (libqorepqc.so, libqoresvm.so, libwasmvm.x86_64.so); imaginea de mai sus este doar linux/amd64, ca și arhiva de versiune.

# 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:

Inițializați directorul de date o singură dată (de exemplu docker compose run --rm qorechain-node init my-node --chain-id qorechain-vladi --home /root/.qorechaind; genesis-ul și configurarea peer-ilor sunt acoperite mai jos), apoi porniți:

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

systemd​

Pentru o instalare pe metal fizic (bare-metal), rulați qorechaind sub 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

Alăturarea la rețea​

1. Inițializare​

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

2. Preluați manifestul​

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

Folosiți acest fișier ca sursă pentru valorile de binar, genesis și peer din pașii de mai jos — verificați jq -r .minCompatible latest.json și rulați cel puțin acea versiune (cea recomandată este jq -r .version latest.json).

3. Descărcați și verificați genesis-ul​

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. Configurați peers și pragul de taxă​

Citiți peers și seeds curenți din manifest, în loc să codificați rigid ID-uri de noduri și hosturi — acestea se rotesc:

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

Deschideți ~/.qorechaind/config/config.toml și setați persistent_peers (și seeds) la aceste valori:

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

Apoi setați prețul minim al gazului în ~/.qorechaind/config/app.toml (pragul de taxă al rețelei: 0.1uqor):

minimum-gas-prices = "0.1uqor"

qorechaind init <moniker> --chain-id qorechain-vladi scrie în app.toml și chain id-ul EVM al rețelei (consultați Limitele nodului); verificați-l pe un director home inițializat cu mult timp în urmă.

5. Porniți sincronizarea​

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

Pornire rapidă (Fast Bootstrap)​

Sincronizarea de la genesis poate dura mult timp. Pentru integrări, folosiți state sync sau un instantaneu (snapshot) pentru o pornire rapidă la rece.

State sync​

State sync preia un instantaneu recent al stării aplicației de la servere RPC de încredere, în loc să redea fiecare bloc. Configurați secțiunea [statesync] din 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"

Preluați trust_height / trust_hash din câmpul stateSync al manifestului — este actualizat orar, deci este sursa preferată:

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

Ca alternativă/rezervă, puteți deriva singuri o înălțime și un hash de încredere din RPC-ul public:

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

Restaurare din instantaneu (snapshot)​

Alternativ, descărcați instantaneul publicat al datelor lanțului, verificați-i suma de control și extrageți-l peste directorul dumneavoastră de date. Pe mainnet, obiectul snapshot din manifest oferă URL-ul, height (înălțimea blocului), dimensiunea și SHA-256 (manifestul de testnet conține în prezent doar URL-ul, așa că folosiți state sync acolo). Citiți snapshot.height înainte de a-l folosi: instantaneul de mainnet este o singură arhivă de aproximativ 27 GB, iar unul vechi înseamnă o recuperare lungă (instantaneul de mainnet publicat în prezent este anterior înălțimilor ambelor upgrade-uri, v3.1.94 și v3.2.0, așa că un nod restaurat din el trebuie să le redea cu un binar v3.2.x).

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
notă

Câmpurile snapshot.height și snapshot.ts din manifest arată cât de proaspătă este arhiva, iar state sync (mai sus) este de obicei mai rapid decât o descărcare de 27 GB. Verificați întotdeauna suma de control înainte de a extrage și folosiți o versiune de nod care conține toate handler-ele de upgrade (consultați avertismentul de la începutul acestei pagini) când redați starea dintr-un instantaneu.

Pruning și indexare​

Ajustați pruning-ul și indexarea tranzacțiilor în funcție de integrarea dumneavoastră. Exchange-urile care au nevoie de istoricul complet al tranzacțiilor ar trebui să ruleze cu pruning minim și cu un indexator de tranzacții activat.

Pruning (app.toml)​

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

# Keep everything — required for archive / full historical queries
# pruning = "nothing"
pruningComportamentCaz de utilizare
defaultPăstrează starea recentă, elimină restulNod RPC, interogări de sold/stare
nothingPăstrează toată starea istoricăNod de arhivă, istoric complet
customValori de reținere/interval definite de operatorRetenție personalizată

Limitele nodului (app.toml)​

Începând cu versiunea de nod v3.2.1, init scrie o secțiune [qorechain] cu trei limite locale ale nodului. Acestea schimbă doar ce păstrează acest nod în memorie și ce include în blocurile pe care le propune, niciodată ce trebuie să conțină un bloc pentru a fi valid:

[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 scrie de asemenea chain id-ul EVM al rețelei în setarea evm-chain-id din secțiunea [evm] a fișierului app.toml (9801 pentru --chain-id qorechain-vladi, 9800 pentru qorechain-diana). Un nod al cărui app.toml conține o altă valoare pornește totuși, dar înregistrează o eroare la pornire, iar propriul său JSON-RPC (eth_chainId, semnarea față de acel nod) răspunde cu un chain id greșit până când corectați fișierul; consensul nu este afectat. Binarele mai vechi scriau valoarea de testnet (9800) indiferent de --chain-id, așa că un nod de mainnet inițializat cu mult timp în urmă ar trebui să-și verifice această setare. Nu setați QORE_EVM_CHAIN_ID la o valoare diferită de cea a rețelei: un astfel de nod refuză să pornească.

Indexarea tranzacțiilor (config.toml)​

[tx_index]
indexer = "kv"

Setați indexer = "kv" (sau un indexator mai bogat) astfel încât tranzacțiile să poată fi interogate după hash și eveniment — esențial pentru exchange-urile care reconciliază depozite și retrageri. Setați indexer = "null" doar dacă nu aveți nevoie de interogări istorice ale tranzacțiilor.

Expunerea endpoint-urilor pentru integrare​

Activați și legați serverele API de care au nevoie integratorii în app.toml:

[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"

Endpoint-urile publice servesc namespace-urile eth_, net_, web3_ și txpool_. Namespace-ul qor_ nu este servit de nicio versiune lansată a nodului, așa că nu îl adăugați (consultați namespace-ul qor_).

Și listenerul RPC în config.toml:

[rpc]
laddr = "tcp://0.0.0.0:26657"
EndpointPortUtilizare
RPC26657Difuzarea tranzacțiilor, interogarea blocurilor/statusului
REST1317Interogări HTTP ale stării lanțului
gRPC9090Acces programatic de mare debit (high-throughput)
EVM JSON-RPC8545Integrări compatibile Ethereum (chain ID 9801)
EVM WS8546Abonamente la evenimente EVM
SVM RPC8899Citiri compatibile Solana (tranzacțiile SVM sunt dezactivate)
avertisment

Nu expuneți niciodată RPC, EVM JSON-RPC sau gRPC direct pe internetul public fără un reverse proxy, limitare de rată (rate limiting), autentificare și un firewall. Legați (bind) la 0.0.0.0 doar în spatele unui strat de ingress controlat.

Monitorizarea sănătății și sincronizării​

Statusul sincronizării​

curl -s localhost:26657/status | jq '.result.sync_info.catching_up'
  • true — încă se sincronizează.
  • false — complet sincronizat și servește starea curentă.
# Latest height and network
curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height, .result.node_info.network'

Câmpul network ar trebui să raporteze qorechain-vladi (mainnet) sau qorechain-diana (testnet).

Prometheus și Grafana​

Nodul poate expune metrici Prometheus pe portul 26660 (setați prometheus = true în secțiunea [instrumentation] din config.toml):

http://localhost:26660/metrics

Colectați aceste metrici cu orice colector compatibil Prometheus. Dacă rulați stiva de monitorizare din Docker Compose, Grafana este disponibil la http://localhost:3001 — setați-vă propriile credențiale la prima conectare. Urmăriți întârzierea înălțimii blocului, numărul de peers și utilizarea resurselor; alertați atunci când catching_up rămâne true sau numărul de peers scade la zero.

Verificarea endpoint-ului EVM​

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

Bune practici operaționale​

  1. Fixați versiunea de lanț. Rulați versiunea recomandată de manifest (v3.2.1 pe mainnet), urmăriți versiunile oficiale pentru upgrade-uri coordonate și mențineți ceasul sistemului sincronizat prin NTP.

  2. Rulați noduri redundante. Operați cel puțin două noduri în spatele unui load balancer, astfel încât o singură repornire sau resincronizare să nu întrerupă traficul de integrare.

  3. Verificați genesis-ul și instantaneele. Validați întotdeauna suma de control SHA-256 a genesis-ului și orice sumă de control a instantaneelor față de versiunea oficială înainte de pornire.

  4. Protejați endpoint-urile publice. Puneți RPC/EVM/gRPC în spatele unui reverse proxy, cu limitare de rată și firewall. Nu expuneți niciodată RPC de scriere neautentificat pe internet.

  5. Potriviți pruning-ul cu nevoia. Folosiți pruning = "nothing" plus tx_index = "kv" pentru exchange-urile care reconciliază istoricul complet de depozite/retrageri; folosiți default pentru interogări ușoare.

  6. Monitorizați sincronizarea continuu. Alertați la întârzierea înălțimii blocului, zero peers și un nod blocat în catching_up.

O implementare doar-nod nu semnează niciodată. Tranzacțiile pe care integrarea dumneavoastră le difuzează prin ea trebuie să poarte deja semnătura hibridă post-cuantică (iar, pentru lane-ul EVM, expeditorul are nevoie de o cheie înregistrată și de o fereastră de autorizare deschisă); consultați Integrarea cu exchange-uri și Semnarea post-cuantică.

Pentru a observa rețeaua fără a rula un nod complet, consultați documentația Light Node.

Depanare (Troubleshooting)​

Nodul se oprește cu o eroare de ceas​

Începând cu versiunea de nod v3.2.1, motorul de consens se oprește când ceasul sistemului are o abatere de mai mult de 60 de secunde față de rețea. Rulați un client NTP (chrony sau systemd-timesyncd), confirmați că ceasul este sincronizat cu timedatectl status, apoi reporniți nodul.

Un nod oprit înainte de upgrade nu își reia funcționarea după înlocuirea binarului​

Dacă nodul dumneavoastră era deja oprit sau blocat înainte de a-i actualiza binarul, simpla introducere a noului binar și repornirea nu este suficientă — nodul are rezultate ABCI învechite, memorate din rularea veche, și nu va re-executa blocul care a cauzat oprirea. Faceți rollback explicit înainte de a reporni:

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

Comanda este qorechaind rollback (o subcomandă de nivel superior) — nu există o subcomandă comet rollback și nici un flag --hard pentru ea.

Restaurarea din instantaneu intră în buclă de eșec (crash-loop) din cauza lipsei priv_validator_state.json​

O arhivă/instantaneu publicat(ă) nu include data/priv_validator_state.json, iar nodul refuză să pornească fără el. Dacă lipsește după o restaurare din instantaneu, creați-l — dar doar dacă nu există deja unul. Nu suprascrieți niciodată unul real: pe un validator, acest fișier este garda anti-dublă-semnare, iar suprascrierea lui riscă o dublă semnare.

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

Pași următori​