Passa al contenuto principale

Guida EVM

@qorechain/evm è un adattatore sottile e type-safe basato su viem per il motore EVM di QoreChain. Non reimplementa un client EVM — viem è una peer dependency. Aggiunge una factory di client consapevole della catena (con auto-rilevamento dell'EVM chain-id), helper ERC-20, wrapper per il deploy/la chiamata di contratti e binding tipizzati per i precompilati EVM di QoreChain.

npm i @qorechain/evm viem

Definizioni di chain e helper per la finestra (0.12.0)​

@qorechain/evm esporta le definizioni di chain viem qorechain (chain id 9801) e qorechainTestnet (9800), più QORECHAIN_CHAINS e QORECHAIN_REST_ENDPOINTS, così un'app viem o wagmi non deve scriverle a mano:

import { createPublicClient, http } from "viem";
import { qorechainTestnet } from "@qorechain/evm";

const publicClient = createPublicClient({ chain: qorechainTestnet, transport: http() });

Include anche gli helper della finestra di autorizzazione: evmWindowStatus legge la finestra di un account via REST, openEvmWindowMessage controlla i limiti della chain e compone il MsgOpenEVMWindow della lane Native da firmare in modalità ibrida, evmWindowCost e weiToUqorCeil dimensionano una finestra, e toQorAddress / toEvmAddress convertono un account eth-native tra le sue due codifiche. Gli helper della finestra sono pubblicati anche senza viem come @qorechain/evm/window. Sono arrivati nella 0.11.0 solo su npm e sono nella 0.12.0 e successive.

Creare un client​

createEvmClient restituisce un bundle di client basato su viem. Rileva automaticamente l'EVM chain id tramite eth_chainId a meno che tu non passi chainId.

import { createEvmClient } from "@qorechain/evm";

const client = await createEvmClient({
endpoints: { evmRpc: "https://evm-testnet.qore.host" }, // mainnet: https://evm.qore.host
});

console.log(await client.getChainId());
// client.publicClient — a viem PublicClient for reads

Puoi anche passare direttamente rpcUrl (mutuamente esclusivo con endpoints), un wsUrl / endpoints.evmWs per WebSocket (wss://evm-ws-testnet.qore.host sulla testnet), un chainId esplicito e decimals (predefinito a 18, la convenzione EVM per QOR — distinta dalla base Cosmos uqor di 10^6).

Deriva un account di firma EVM da una chiave privata:

import { evmAccountFromPrivateKey } from "@qorechain/evm";

const account = evmAccountFromPrivateKey("0x...");

Helper ERC-20​

Il namespace erc20 (e le singole funzioni) incapsula le chiamate ERC-20 standard. Le letture richiedono un public client viem; le scritture richiedono un wallet client.

import { erc20 } from "@qorechain/evm";

const bal = await erc20.balanceOf(client.publicClient, token, account);
const meta = await erc20.metadata(client.publicClient, token); // Erc20Metadata
const allowed = await erc20.allowance(client.publicClient, token, owner, spender);

// writes (need a wallet client)
// await erc20.transfer(walletClient, token, to, amount);
// await erc20.approve(walletClient, token, spender, amount);

L'ABI grezza è esportata come ERC20_ABI se preferisci chiamare viem direttamente.

Contratti​

Wrapper generici per deploy e chiamata:

import { deployContract, readContract, writeContract } from "@qorechain/evm";

// const address = await deployContract(walletClient, { abi, bytecode, args });
// const value = await readContract(client.publicClient, { address, abi, functionName, args });
// const hash = await writeContract(walletClient, { address, abi, functionName, args });

Finestra di autorizzazione EVM (dalla chain v3.2.0)​

Dalla versione v3.2.0 della chain (mainnet dal blocco 2,981,742, testnet dal blocco 5,920,000) la corsia EVM ammette una transazione solo da un account che abbia una chiave ML-DSA-87 registrata e una finestra di autorizzazione aperta. Le letture (eth_call, saldi, ricevute) e la stima del gas funzionano senza finestra, e wallet e librerie come MetaMask, viem, ethers, Hardhat e Foundry firmano come prima; ciò che cambia è che l'autorizzazione post-quantistica viaggia prima della transazione, come messaggio della corsia Native firmato in modo ibrido. Le regole a livello di chain, i limiti, le forme della CLI e i codici di rifiuto sono in Finestra di autorizzazione EVM.

Con l'SDK 0.8.2 o successivo puoi aprire una finestra dal codice (la 0.9.0 aggiunge le opzioni di ambito qui sotto). La registrazione della chiave (una sola volta) è descritta in Firma ibrida; l'esempio seguente apre poi una finestra per un account eth-native unificato (npm i @cosmjs/stargate):

import { StargateClient } from "@cosmjs/stargate";
import {
createClient,
deriveUnifiedAccount,
EthNativeSigner,
openEvmWindowMsg,
fetchEvmWindow,
classifyEvmWindowRejection,
} from "@qorechain/sdk";

const REST = "https://api.qore.host";
const RPC = "https://rpc.qore.host";

const client = createClient({ network: "mainnet", endpoints: { rest: REST, rpc: RPC } });
const transport = await StargateClient.connect(RPC);
const account = await deriveUnifiedAccount(mnemonic);
const signer = new EthNativeSigner(account, { rest: REST }); // hybrid: the window needs the ML-DSA key

const { account: base } = await client.rest.get<{
account: { account_number: string; sequence: string };
}>(`/cosmos/auth/v1beta1/accounts/${account.cosmos}`);

const open = openEvmWindowMsg({
sender: account.cosmos,
blocks: 7200, // 1 … 17,280 blocks (a block count, not a duration)
maxTxs: 20, // 1 … 1,000 transactions
maxValue: "1000000000", // uqor: transferred value PLUS the maximum fee of each transaction
});

await signer.signAndBroadcast(transport, {
chainId: "qorechain-vladi",
accountNumber: BigInt(base.account_number),
sequence: BigInt(base.sequence),
messages: [open],
fee: { amount: [{ denom: "uqor", amount: "40000" }], gas: "400000" },
});

const w = await fetchEvmWindow({ rest: REST, address: account.cosmos });
console.log(w.live); // true while the window admits at least one more transaction

L'apertura di una finestra fa avanzare il nonce dell'account (una sola identità: la sequence Cosmos è il nonce EVM), quindi leggi il nonce EVM dopo che la finestra è aperta e firma a quel punto la transazione EVM. maxValue limita il valore più la fee massima (gas limit per il fee cap) di ciascuna transazione: un trasferimento di 1,000 uqor con 21,000 gas a 112.5 gwei consuma 3,363 uqor della finestra. Apri una finestra solo quando l'utente lo richiede; non aprirne mai una automaticamente.

Quando la corsia EVM rifiuta una transazione, classifyEvmWindowRejection(err) te ne indica il motivo:

try {
// send the EVM transaction (viem, ethers, ...)
} catch (err) {
const why = classifyEvmWindowRejection(err);
// "no-pqc-key" | "no-window" | "exhausted" | "invalid" | undefined
}

closeEvmWindowMsg costruisce il corrispondente messaggio di chiusura, e MAX_EVM_WINDOW_BLOCKS e MAX_EVM_WINDOW_TXS esportano i limiti.

Limitare l'ambito di una finestra (dalla chain v3.2.3, SDK 0.9.0)​

Una finestra può essere ristretta quando viene aperta: nativeOnly ammette solo trasferimenti semplici di QOR nativo (nessun calldata, nessuna creazione di contratti, nessun destinatario che contenga codice, nessuna autorizzazione EIP-7702), e allowedTargets ammette solo transazioni il cui destinatario è uno fino a 16 indirizzi 0x elencati (nessun duplicato; la creazione di contratti viene rifiutata). Entrambi sono nuovi campi del messaggio: un nodo precedente alla v3.2.3 rifiuta l'intera transazione se uno dei due è impostato, quindi impostali solo su una rete che ha applicato la v3.2.3 (lo hanno fatto entrambe le reti pubbliche). fetchEvmWindow li legge entrambi (nativeOnly, allowedTargets; prima della v3.2.3 risultano false e vuoto). Per una finestra aperta solo per inviare QOR, preferisci nativeOnly. allowedTargets limita quali contratti e token la finestra può toccare, non quanto: un token elencato ammette qualsiasi importo di esso, incluso approve, e un contratto elencato può spostare tutto ciò che il suo codice e le approvazioni esistenti consentono, quindi non elencare contratti generici di forwarder o router. Una finestra limita solo le transazioni sulla corsia EVM (firmate in modo classico); i messaggi Cosmos firmati con la firma ibrida PQC, come le chiamate cross-VM e authz, ne sono fuori.

import {
createClient,
deriveNativeAccount,
directSignerFromPrivateKey,
derivePqcCanonical,
openEvmWindowMsg,
} from "@qorechain/sdk";

const client = createClient({
network: "mainnet",
endpoints: { rest: "https://api.qore.host", rpc: "https://rpc.qore.host", evmRpc: "https://evm.qore.host" },
});
const account = await deriveNativeAccount(mnemonic);
const signer = await directSignerFromPrivateKey(account.privateKey, "qor");
const pqcKeypair = derivePqcCanonical(account.address, mnemonic); // already registered on-chain
const tx = await client.connectTx(signer, { pqcKeypair }); // signs hybrid

await tx.signAndBroadcast(
[
openEvmWindowMsg({
sender: account.address,
blocks: 7200,
maxTxs: 20,
maxValue: "1000000000", // uqor: value PLUS the maximum fee of each transaction
nativeOnly: true,
// or: allowedTargets: ["0x…", "0x…"],
}),
],
"auto",
);

Altre liste di ambito (dalla chain v3.2.8, SDK 0.14.0)​

Dalla chain v3.2.8 (la testnet dal 12 novembre 2026; la mainnet non l'ha applicata) una finestra può portare tre liste in più, che openEvmWindowMsg accetta dall'SDK 0.14.0: validators (fino a 16 indirizzi di contratto la cui verifica della firma dell'account vale per le azioni dell'account stesso, come un modulo validatore o un entry point ERC-4337), stakingValidators (validatori qorvaloper1... ai quali la finestra può delegare o ridelegare tramite il precompile di staking) e ibcReceivers (destinatari ICS-20, ciascuno scritto "<channel>/<receiver>"). Il builder controlla il formato e rifiuta i duplicati prima che venga firmato qualsiasi cosa. Impostale solo su una rete che esegue la v3.2.8: un nodo precedente rifiuta il messaggio. fetchEvmWindow non restituisce queste tre liste, e nemmeno la route REST della finestra le restituisce nella v3.2.8: conserva i valori con cui hai aperto la finestra. Una chiamata che imposta tutte e tre le liste è stata eseguita sulla testnet il 12 novembre 2026 con l'SDK 0.14.0 ed è riuscita con code 0 (195,233 di gas usato); la lettura REST ha elencato allowed_targets e non ha restituito le altre due liste:

openEvmWindowMsg({
sender: account.address,
blocks: 7200,
maxTxs: 20,
maxValue: "1000000000",
allowedTargets: ["0x1111111111111111111111111111111111111111"], // your token contract
});

Per lo staking e per riscuotere le ricompense usa i messaggi Cosmos nativi (QoreX, oppure i comandi staking e distribution di qorechaind); i campi di finestra qui sopra descrivono ciò che la chain accetta, ma fare staking da MetaMask non è un percorso supportato.

Vedi il riferimento della finestra EVM per le regole.

Una transazione di tipo 4 (EIP-7702) viene ammessa solo dopo che ogni account la cui autorizzazione ha effetto ha dato un consenso post-quantistico esattamente a quel delegato, con un MsgAuthorizeEVMDelegation firmato in modo ibrido. Il consenso viene esaurito dalla transazione che installa la delega e scade dopo i blocks che hai impostato (da 1 a 17,280); l'indirizzo zero come delegato acconsente alla rimozione. L'SDK costruisce i messaggi e rilegge il consenso, incluso il nonce che la tupla di autorizzazione deve portare:

import {
authorizeEvmDelegationMsg,
clearEvmDelegationMsg,
fetchEvmDelegationConsent,
evmDelegationTupleNonce,
} from "@qorechain/sdk";

// 1) Consent to one delegate (hybrid-signed Native-lane message, `tx` as above).
await tx.signAndBroadcast(
[authorizeEvmDelegationMsg({ sender: account.address, delegate: "0xDelegate…", blocks: 600 })],
"auto",
);

// 2) Read the consent: the tuple's nonce is the account's EVM nonce for a
// sponsored transaction, and that nonce + 1 when the account sends it itself.
const consent = await fetchEvmDelegationConsent({ rest: "https://api.qore.host", address: account.address });
const tupleNonce = evmDelegationTupleNonce(consent, /* sponsored */ true);

// 3) Sign the authorisation tuple with `tupleNonce` and send the type-4
// transaction (the sender still needs an open window; a sponsor pays from its own).

// Remove an installed delegation directly, without any EVM transaction:
// await tx.signAndBroadcast([clearEvmDelegationMsg(account.address)], "auto");

classifyEvmDelegationRejection(err) restituisce "no-consent" oppure "invalid" quando la corsia EVM rifiuta una delega. La query del consenso richiede la chain v3.2.2 o successiva. Le regole a livello di chain sono in Deleghe EIP-7702; le forme della CLI sono qorechaind tx pqc authorize-evm-delegation e clear-evm-delegation.

Le release precedenti alla 0.9.0 costruiscono solo la finestra senza ambito (una finestra senza ambito funziona comunque su entrambe le reti) e non hanno builder di consenso; usa lì le forme della CLI in Finestra di autorizzazione EVM.

Precompilati​

QoreChain espone precompilati richiamabili da contratto a indirizzi fissi. Il namespace precompiles fornisce binding tipizzati, e gli indirizzi e le ABI sono esportati.

Non attivi sulla mainnet; tre sulla testnet. I precompilati di QoreChain sono compilati nel node ma nessuno è attivato sulla mainnet (qorechain-vladi). Sulla testnet (qorechain-diana) l'elenco active_static_precompiles contiene 0x…0A01 (verifica PQC), 0x…0A02 (stato chiave PQC) e 0x…0C01 (parametri di consenso), verificato il 27 ottobre 2026; la coppia AI (0x…0B01, 0x…0B02) non è attiva su nessuna delle due reti, e il bridge cross-VM (0x…0901) non era attivo su nessuna delle due il 27 ottobre (l'elenco della testnet lo conteneva anche dal 4 novembre e lo conteneva ancora il 7 novembre 2026; sulla testnet è attivo con una allowlist ed è stata testata una eth_call in sola lettura il 7 novembre 2026; l'elenco della mainnet è vuoto). Una chiamata a un indirizzo non attivo restituisce dati vuoti, quindi quegli helper generano un errore. Vedi Precompilati EVM: stato della rete.

PrecompilatoFunzioneIndirizzo
Cross-VM Bridge(routing del bridge)0x0000000000000000000000000000000000000901
Verifica PQCpqcVerify0x0000000000000000000000000000000000000a01
Stato chiave PQCpqcKeyStatus0x0000000000000000000000000000000000000a02
Punteggio di rischio QCAIaiRiskScore0x0000000000000000000000000000000000000b01
Controllo anomalie QCAIaiAnomalyCheck0x0000000000000000000000000000000000000b02
Parametri di consensorlConsensusParams0x0000000000000000000000000000000000000c01
import { precompiles, PRECOMPILE_ADDRESSES } from "@qorechain/evm";

// Read consensus parameters (0x…0C01 is active on the testnet, not on mainnet).
const params = await precompiles.rlConsensusParams(client.publicClient);

// Check whether an address has a registered PQC key.
const status = await precompiles.pqcKeyStatus(client.publicClient, account);

// QCAI helpers: raw calldata for the risk score, an args object for the anomaly check.
const score = await precompiles.aiRiskScore(client.publicClient, "0xa9059cbb...");
const anomaly = await precompiles.aiAnomalyCheck(client.publicClient, {
sender: account,
amount: 1_000_000_000_000_000_000n, // 1 QOR in wei
});

console.log(PRECOMPILE_ADDRESSES.crossVmBridge);

Le ABI dei precompilati sono esportate come IQORE_PQC_ABI, IQORE_AI_ABI e IQORE_CONSENSUS_ABI.

Dove un precompilato non è attivo (mainnet: tutti; testnet: la coppia AI e il bridge cross-VM), oppure su un nodo privo dei precompilati di QoreChain, queste chiamate generano un errore "feature not present". Gestiscilo per ogni chiamata.

Vedi l'esempio evm-precompile per una versione eseguibile.