Passa al contenuto principale

JSON-RPC — Namespace eth_

QoreChain implementa un'interfaccia JSON-RPC compatibile con EVM, che consente ai tool standard dell'ecosistema Ethereum (MetaMask, Hardhat, Foundry, ethers.js, web3.js) di leggere lo stato della chain e stimare il gas senza alcuna modifica. L'invio di una transazione dalla lane EVM richiede un passaggio in più a partire dalla versione della chain v3.2.0: l'account mittente deve avere una chiave post-quantistica registrata e una finestra di autorizzazione EVM aperta (vedi Invio di transazioni).

Connessione​

TrasportoIndirizzo predefinito
HTTPhttp://localhost:8545
WebSocketws://localhost:8546
nota

L'interfaccia JSON-RPC EVM è servita dalla mainnet qorechain-vladi (chain ID EVM 9801, hex 0x2649, release del nodo v3.2.7 dal 12 novembre 2026 all'altezza 4.164.600, attiva dal 7 giugno 2026) e dalla testnet qorechain-diana (chain ID EVM 9800, hex 0x2648, release del nodo v3.2.8 dal 12 novembre 2026 all'altezza 9.929.500, la mainnet esegue la v3.2.7). Dalla v3.2.7 (testnet dal 6 novembre 2026, mainnet dal 12 novembre 2026) eth_getBlockByNumber, eth_getBlockReceipts e eth_feeHistory rispondono in modo più affidabile, anche per i blocchi che contengono una transazione EVM fallita. Gli indirizzi locali sopra riportati si applicano a un nodo eseguito in proprio. Gli endpoint HTTP pubblici sono https://evm.qore.host (mainnet) e https://evm-testnet.qore.host (testnet), elencati in Reti. L'unico WebSocket EVM pubblico è quello della testnet (wss://evm-ws-testnet.qore.host); non esiste un WebSocket EVM pubblico per la mainnet.

Namespace supportati​

NamespaceDescrizione
eth_Metodi JSON-RPC Ethereum principali
web3_Metodi di utilità (versione client, hashing)
net_Metodi sullo stato della rete
txpool_Ispezione del pool delle transazioni
rpc_Introspezione del server (rpc_modules)

Metodi eth_​

MetodoParametriDescrizione
eth_blockNumbernessunoRestituisce il numero dell'ultimo blocco
eth_getBalanceaddress, blockNumberRestituisce il saldo di un indirizzo in wei
eth_getTransactionCountaddress, blockNumberRestituisce il nonce (numero di transazioni) di un indirizzo
eth_sendRawTransactionsignedTxDataInvia una transazione firmata per la trasmissione
eth_callcallObject, blockNumberEsegue una chiamata in sola lettura sull'EVM
eth_estimateGascallObjectStima il gas necessario per una transazione
eth_getBlockByNumberblockNumber, fullTx (bool)Restituisce i dati del blocco per numero
eth_getTransactionByHashtxHashRestituisce i dati della transazione per hash
eth_getTransactionReceipttxHashRestituisce la ricevuta di una transazione minata
eth_getLogsfilterObjectRestituisce i log corrispondenti a un filtro
eth_chainIdnessunoRestituisce il chain ID (codificato in hex)
eth_gasPricenessunoRestituisce il prezzo del gas corrente in wei
eth_feeHistoryblockCount, newestBlock, rewardPercentilesRestituisce i dati storici sulle fee (EIP-1559)
eth_getBlockByHashblockHash, fullTx (bool)Restituisce i dati del blocco per hash
eth_getCodeaddress, blockNumberRestituisce il bytecode di un contratto
eth_getStorageAtaddress, slot, blockNumberRestituisce uno slot di storage
eth_getBlockReceiptsblockNumberRestituisce tutte le ricevute di un blocco
eth_getProofaddress, storageKeys, blockNumberRestituisce una prova di account
eth_createAccessListcallObject, blockNumberCostruisce una access list per una chiamata
eth_maxPriorityFeePerGasnessunoRestituisce la priority fee suggerita (wei)
eth_syncingnessunoRestituisce false quando il nodo è allineato
eth_newFilter, eth_newBlockFilter, eth_getFilterChangesoggetto filtro / ID filtroFiltri a polling

Metodi web3_​

MetodoParametriDescrizione
web3_clientVersionnessunoRestituisce la stringa di versione del client
web3_sha3data (hex)Restituisce l'hash Keccak-256 dell'input

Metodi txpool_​

MetodoParametriDescrizione
txpool_statusnessunoRestituisce il numero di transazioni in sospeso e in coda
txpool_contentnessunoRestituisce le transazioni in sospeso e in coda (non sugli endpoint pubblici)
txpool_inspectnessunoRestituisce un riepilogo del pool (non sugli endpoint pubblici)

Metodi net_​

MetodoParametriDescrizione
net_versionnessunoRestituisce l'ID della rete
net_listeningnessunoRestituisce true se il nodo è in ascolto
net_peerCountnessunoRestituisce il numero di peer connessi (hex)

Configurazione​

Abilita e configura il server JSON-RPC in app.toml:

[json-rpc]
# Enable the JSON-RPC server
enable = true

# HTTP server address
address = "0.0.0.0:8545"

# WebSocket server address
ws-address = "0.0.0.0:8546"

# Enabled API namespaces (a node initialised by v3.2.3 or later defaults to "eth,net,web3";
# txpool is opt-in because it publishes the node's pending transactions)
api = "eth,web3,net,txpool"

# Maximum number of logs returned by eth_getLogs
filter-cap = 10000

# Maximum gas for eth_call and eth_estimateGas
gas-cap = 25000000

# EVM execution timeout
evm-timeout = "5s"

# Transaction fee cap (in QOR)
txfee-cap = 1

# Maximum open WebSocket connections
max-open-connections = 0

Limiti sugli endpoint pubblici​

nota
  • eth_getLogs accetta al massimo 10.000 blocchi tra fromBlock e toBlock. Un intervallo più ampio restituisce {"code":-32000,"message":"maximum [from, to] blocks distance: 10000"}. Interroga con finestre di 10.000 blocchi o meno. L'impostazione separata filter-cap limita il numero di log restituiti.
  • txpool_status funziona sugli endpoint pubblici. txpool_content e txpool_inspect sono disabilitati sia sull'endpoint mainnet pubblico sia su quello testnet pubblico (funzionano su un nodo eseguito in proprio, con txpool nel suo elenco api).
  • I metodi debug_* e eth_signTransaction non sono disponibili.
  • eth_subscribe richiede una connessione WebSocket. Via HTTP restituisce -32601 notifications not supported. Vedi Eventi WebSocket.
  • Lo stato alle altezze vecchie viene sottoposto a pruning sugli endpoint pubblici, quindi eth_call su un blocco storico lontano può fallire con un errore di versione dello stato.
  • Se uno script riceve 403 Forbidden, imposta un header User-Agent esplicito; l'agent urllib predefinito di Python è bloccato, mentre i client requests, curl, Node e Go funzionano così come sono.

Invio di transazioni​

La lane EVM richiede una chiave PQC e una finestra aperta

A partire dalla versione della chain v3.2.0 la lane EVM ammette una transazione (MsgEthereumTx, inclusi i deploy di contratti) solo da un account che abbia una chiave post-quantistica registrata e una finestra di autorizzazione EVM aperta. Un normale wallet EVM che non ha eseguito questa configurazione non può inviare transazioni: il nodo le rifiuta con un errore del modulo pqc (codici 26, 27 o 28) invece di includerle. La lettura dei saldi, eth_call e la stima del gas non richiedono alcuna finestra. Dalla v3.2.2 viene rifiutata anche una transazione firmata senza chain id (pre-EIP-155), e dalla v3.2.3 una finestra può essere limitata ai semplici trasferimenti di QOR (native_only) o a destinatari elencati (allowed_targets); una transazione al di fuori dell'ambito viene rifiutata con il codice 27.

Controlla un account prima di inviare:

  • GET /qorechain/pqc/v1/account/{address} (found: true significa che è registrata una chiave)
  • GET /qorechain/pqc/v1/evm_window/{address} (live: true significa che una finestra ammette attualmente transazioni)

Entrambi sono descritti in Endpoint REST / gRPC (la risposta della finestra riporta anche native_only e allowed_targets). Una finestra si apre con una transazione QoreChain (MsgOpenEVMWindow, limitata a un massimo di 17.280 blocchi e 1.000 transazioni più un tetto di valore), non con una transazione Ethereum. Vedi Sviluppo EVM per una panoramica della lane.

Esempi​

eth_blockNumber​

Richiesta:

curl -X POST http://localhost:8545 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_blockNumber",
"params": [],
"id": 1
}'

Risposta:

{
"jsonrpc": "2.0",
"id": 1,
"result": "0x37f559"
}

eth_chainId​

Richiesta:

curl -X POST http://localhost:8545 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_chainId",
"params": [],
"id": 2
}'

Risposta (mainnet qorechain-vladi, chain ID 9801):

{
"jsonrpc": "2.0",
"id": 2,
"result": "0x2649"
}

Sulla testnet qorechain-diana (chain ID 9800) questo metodo restituisce "0x2648".

eth_getBalance​

Richiesta:

curl -X POST http://localhost:8545 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28", "latest"],
"id": 3
}'

Risposta:

{
"jsonrpc": "2.0",
"id": 3,
"result": "0x56bc75e2d63100000"
}

Connessione con ethers.js​

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("http://localhost:8545");

// Get latest block
const block = await provider.getBlockNumber();
console.log("Latest block:", block);

// Get balance
const balance = await provider.getBalance("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28");
console.log("Balance:", ethers.formatEther(balance), "QOR");
informazioni
  • Il chain ID viene restituito come stringa esadecimale. Convertilo in decimale per la configurazione del wallet — 0x2649 corrisponde a 9801 (mainnet), 0x2648 a 9800 (testnet).
  • Il pricing del gas segue il modello EIP-1559. Usa eth_feeHistory per stimare la base fee e la priority fee.
  • Tag di blocco accettati: "latest", "earliest", "pending", oppure un numero di blocco in hex.
  • Limitazioni sui filtri: eth_getLogs è limitato a filter-cap risultati per query (10.000 di default), e gli endpoint pubblici rifiutano intervalli più ampi di 10.000 blocchi. Usa intervalli di blocchi più ristretti per set di dati di grandi dimensioni.