Ghid EVM
@qorechain/evm este un adaptor subțire, type-safe peste viem pentru
motorul EVM al QoreChain. Nu reimplementează un client EVM — viem este o dependență
peer. Adaugă o fabrică de clienți conștientă de lanț (cu auto-detectare a chain-id-ului
EVM), helpere ERC-20, wrappere pentru deploy/apel de contracte și legături tipizate
pentru precompilele EVM ale QoreChain.
npm i @qorechain/evm viem
Definiții de lanț și helpere pentru fereastră (0.12.0)
@qorechain/evm exportă definițiile de lanț viem qorechain (chain id 9801) și
qorechainTestnet (9800), plus QORECHAIN_CHAINS și QORECHAIN_REST_ENDPOINTS, astfel
încât o aplicație viem sau wagmi să nu le scrie de mână:
import { createPublicClient, http } from "viem";
import { qorechainTestnet } from "@qorechain/evm";
const publicClient = createPublicClient({ chain: qorechainTestnet, transport: http() });
Are și helperele ferestrei de autorizare: evmWindowStatus citește
fereastra unui cont prin REST, openEvmWindowMessage verifică limitele chain-ului și
compune MsgOpenEVMWindow din banda Native pentru semnare hibridă, evmWindowCost și
weiToUqorCeil dimensionează o fereastră, iar toQorAddress / toEvmAddress convertesc un
cont eth-native între cele două codificări ale sale. Helperele de fereastră sunt publicate
și fără viem ca @qorechain/evm/window. Au apărut în versiunea 0.11.0, doar pe npm, și sunt în
0.12.0 și ulterior.
Crearea unui client
createEvmClient returnează un pachet de client susținut de viem. Detectează automat
chain-id-ul EVM prin eth_chainId, cu excepția cazului în care transmiți 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
Poți de asemenea să transmiți direct rpcUrl (mutual exclusiv cu endpoints), un
wsUrl / endpoints.evmWs pentru WebSocket (wss://evm-ws-testnet.qore.host pe
testnet), un chainId explicit și decimals
(implicit 18, convenția EVM pentru QOR — distinctă de baza Cosmos uqor
de 10^6).
Derivă un cont de semnare EVM dintr-o cheie privată:
import { evmAccountFromPrivateKey } from "@qorechain/evm";
const account = evmAccountFromPrivateKey("0x...");
Helpere ERC-20
Spațiul de nume erc20 (și funcțiile individuale) împachetează apelurile ERC-20 standard.
Citirile primesc un public client viem; scrierile primesc 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);
ABI-ul brut este exportat ca ERC20_ABI dacă preferi să apelezi viem direct.
Contracte
Wrappere generice pentru deploy și apel:
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 });
Fereastra de autorizare EVM (lanț v3.2.0)
Începând cu versiunea de lanț v3.2.0 (mainnet de la blocul 2,981,742, testnet de la
blocul 5,920,000), banda EVM admite o tranzacție doar de la un cont care are o
cheie ML-DSA-87 înregistrată și o fereastră de autorizare deschisă. Citirile
(eth_call, solduri, chitanțe) și estimarea gazului funcționează fără una, iar
portofelele și bibliotecile precum MetaMask, viem, ethers, Hardhat și Foundry semnează
ca până acum; ceea ce se schimbă este că autorizarea post-cuantică călătorește înaintea
tranzacției, ca mesaj de bandă Native semnat hibrid. Regulile la nivel de lanț, limitele,
formele CLI și codurile de refuz se găsesc în
Fereastra de autorizare EVM.
Cu SDK 0.8.2 sau mai nou poți deschide o fereastră din cod (0.9.0 adaugă
opțiunile de domeniu de mai jos). Înregistrarea cheii
(o singură dată) este descrisă în Semnare hibridă; exemplul
de mai jos deschide apoi o fereastră pentru un cont eth-native unificat (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
Deschiderea unei ferestre avansează nonce-ul contului (o singură identitate: secvența
Cosmos este nonce-ul EVM), așa că citește nonce-ul EVM după ce fereastra este
deschisă și abia apoi semnează tranzacția EVM. maxValue limitează valoarea plus
taxa maximă (limita de gaz înmulțită cu plafonul taxei) a fiecărei tranzacții: un
transfer de 1,000 uqor cu 21,000 de gaz la 112.5 gwei consumă 3,363 uqor din fereastră.
Deschide o fereastră doar când utilizatorul o cere; nu deschide niciodată una automat.
Când banda EVM refuză o tranzacție, classifyEvmWindowRejection(err) îți spune
de ce:
try {
// send the EVM transaction (viem, ethers, ...)
} catch (err) {
const why = classifyEvmWindowRejection(err);
// "no-pqc-key" | "no-window" | "exhausted" | "invalid" | undefined
}
closeEvmWindowMsg construiește mesajul de închidere corespunzător, iar
MAX_EVM_WINDOW_BLOCKS și MAX_EVM_WINDOW_TXS exportă limitele.
Domeniul unei ferestre (lanț v3.2.3, SDK 0.9.0)
O fereastră poate fi restrânsă la deschidere: nativeOnly admite doar transferuri
simple de QOR nativ (fără calldata, fără creare de contract, fără destinatar care
poartă cod, fără autorizare EIP-7702), iar allowedTargets admite doar tranzacții al
căror destinatar este una dintre cel mult 16 adrese 0x listate (fără duplicate;
crearea de contract este refuzată). Ambele sunt câmpuri noi de mesaj: un nod sub v3.2.3
refuză întreaga tranzacție când oricare dintre ele este setat, așa că setează-le doar pe
o rețea care a aplicat v3.2.3 (ambele rețele publice au aplicat-o). fetchEvmWindow le
citește înapoi pe ambele (nativeOnly, allowedTargets; înainte de v3.2.3 se citesc
false și gol). Pentru o fereastră deschisă doar pentru a trimite QOR, preferă
nativeOnly. allowedTargets limitează ce contracte și tokenuri poate atinge fereastra, nu cât: un token listat admite orice sumă din el, inclusiv approve, iar un contract listat poate muta tot ce permit codul lui și aprobările existente, așa că nu lista contracte generice de tip forwarder sau router. O fereastră limitează doar tranzacțiile de pe banda EVM (semnate clasic); mesajele Cosmos semnate cu semnătura hibridă PQC, precum apelurile cross-VM și authz, sunt în afara ei.
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",
);
Mai multe liste de domeniu (de la lanțul v3.2.8, SDK 0.14.0)
De la lanțul v3.2.8 (testnet-ul din 12 noiembrie 2026; mainnet nu l-a aplicat) o
fereastră poate purta încă trei liste, pe care openEvmWindowMsg le acceptă de la SDK 0.14.0:
validators (până la 16 adrese de contract a căror verificare a semnăturii contului
contează pentru acțiunile proprii ale contului, cum ar fi un modul de validare sau un
punct de intrare ERC-4337), stakingValidators (validatori qorvaloper1... către care
fereastra poate delega sau redelega prin precompile-ul de staking) și ibcReceivers
(destinatari ICS-20, fiecare scris "<channel>/<receiver>"). Constructorul verifică
formatul și refuză duplicatele înainte de orice semnare. Setați-le doar pe o rețea care
rulează v3.2.8: un nod sub această versiune refuză mesajul.
fetchEvmWindow nu returnează aceste trei liste, iar ruta REST a ferestrei nu le returnează nici ea în v3.2.8: păstrați valorile cu care ați deschis fereastra. Un apel de această
formă (cu toate cele trei liste setate) a fost rulat pe
testnet pe 12 noiembrie 2026 cu SDK 0.14.0 și a reușit cu cod 0 (195.233 gaz folosit); citirea
înapoi prin REST a listat allowed_targets și nu a returnat celelalte două liste:
openEvmWindowMsg({
sender: account.address,
blocks: 7200,
maxTxs: 20,
maxValue: "1000000000",
allowedTargets: ["0x1111111111111111111111111111111111111111"], // your token contract
});
Pentru staking și pentru revendicarea recompenselor, folosiți mesajele Cosmos native (QoreX sau comenzile qorechaind de staking și distribution); câmpurile ferestrei de mai sus descriu ce acceptă lanțul, dar staking-ul din MetaMask nu este o cale susținută.
Vedeți referința ferestrei EVM pentru reguli.
Consimțământul EIP-7702 (lanț v3.2.2, SDK 0.9.0)
O tranzacție de tip 4 (EIP-7702) este admisă doar după ce fiecare cont a cărui
autorizare intră în vigoare a dat un consimțământ post-cuantic exact pentru acel
delegat, printr-un MsgAuthorizeEVMDelegation semnat hibrid. Consimțământul este
consumat de tranzacția care instalează delegarea și expiră după blocks pe care îl
setezi (1 până la 17,280); adresa zero ca delegat consimte la ștergere. SDK-ul
construiește mesajele și citește înapoi consimțământul, inclusiv nonce-ul pe care
trebuie să-l poarte tuplul de autorizare:
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) returnează "no-consent" sau "invalid" când
banda EVM refuză o delegare. Interogarea consimțământului necesită lanț v3.2.2 sau mai
nou. Regulile la nivel de lanț se găsesc în
Delegări EIP-7702; formele CLI sunt
qorechaind tx pqc authorize-evm-delegation și clear-evm-delegation.
Versiunile anterioare lui 0.9.0 construiesc doar fereastra fără domeniu (o fereastră fără domeniu funcționează în continuare pe ambele rețele) și nu au constructori de consimțământ; folosește acolo formele CLI din Fereastra de autorizare EVM.
Precompile
QoreChain definește precompile apelabile din contracte la adrese fixe. Spațiul de nume
precompiles oferă legături tipizate, iar adresele și ABI-urile sunt
exportate.
Inactive pe mainnet; trei pe testnet. Precompilele QoreChain sunt compilate în nod, dar niciuna nu este activată pe mainnet (
qorechain-vladi). Pe testnet (qorechain-diana), listaactive_static_precompilesconține0x…0A01(verificare PQC),0x…0A02(starea cheii PQC) și0x…0C01(parametrii de consens), verificat la 27 octombrie 2026; perechea AI (0x…0B01,0x…0B02) nu este activă pe niciuna dintre rețele, iar puntea cross-VM (0x…0901) nu era activă pe niciuna pe 27 octombrie (lista testnet-ului o conținea și pe ea din 4 noiembrie și tot o conținea pe 7 noiembrie 2026; pe testnet este activă cu o listă de permisiuni și a fost testat uneth_calldoar-citire pe 7 noiembrie 2026; lista mainnet-ului este goală). Un apel către o adresă inactivă returnează date goale, deci acele helpere aruncă eroare. Vezi Precompile EVM: Starea rețelei.
| Precompilă | Funcție | Adresă |
|---|---|---|
| Cross-VM Bridge | (rutare bridge) | 0x0000000000000000000000000000000000000901 |
| Verificare PQC | pqcVerify | 0x0000000000000000000000000000000000000a01 |
| Stare cheie PQC | pqcKeyStatus | 0x0000000000000000000000000000000000000a02 |
| Scor de risc QCAI | aiRiskScore | 0x0000000000000000000000000000000000000b01 |
| Verificare anomalii QCAI | aiAnomalyCheck | 0x0000000000000000000000000000000000000b02 |
| Parametri de consens | rlConsensusParams | 0x0000000000000000000000000000000000000c01 |
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);
ABI-urile precompilelor sunt exportate ca IQORE_PQC_ABI, IQORE_AI_ABI și
IQORE_CONSENSUS_ABI.
Acolo unde o precompilă nu este activă (mainnet: toate; testnet: perechea AI și puntea cross-VM), sau pe un nod fără precompilele QoreChain, aceste apeluri aruncă o eroare „feature not present”. Tratează acest lucru per apel.
Vezi exemplul evm-precompile pentru o versiune executabilă.