Guide EVM
@qorechain/evm est un adaptateur fin et fortement typé au-dessus de viem pour
le moteur EVM de QoreChain. Il ne réimplémente pas un client EVM — viem est une dépendance
pair (peer dependency). Il ajoute une fabrique de client consciente de la chaîne (avec
détection automatique de l'identifiant de chaîne EVM), des assistants ERC-20, des wrappers de
déploiement/appel de contrats, et des liaisons typées pour les précompilés EVM de QoreChain.
npm i @qorechain/evm viem
Définitions de chaîne et assistants de fenêtre (0.12.0)
@qorechain/evm exporte les définitions de chaîne viem qorechain (chain id 9801) et
qorechainTestnet (9800), ainsi que QORECHAIN_CHAINS et QORECHAIN_REST_ENDPOINTS, de sorte
qu'une application viem ou wagmi n'ait pas à les écrire à la main :
import { createPublicClient, http } from "viem";
import { qorechainTestnet } from "@qorechain/evm";
const publicClient = createPublicClient({ chain: qorechainTestnet, transport: http() });
Il fournit aussi les assistants de la fenêtre d'autorisation : evmWindowStatus lit
la fenêtre d'un compte via REST, openEvmWindowMessage vérifie les bornes de la chaîne et
compose le MsgOpenEVMWindow de la voie Native à signer en hybride, evmWindowCost et
weiToUqorCeil dimensionnent une fenêtre, et toQorAddress / toEvmAddress convertissent un
compte eth-native entre ses deux encodages. Les assistants de fenêtre sont aussi publiés
sans viem sous @qorechain/evm/window. Ils sont arrivés dans la 0.11.0 (npm uniquement) et sont dans la
0.12.0 et les versions ultérieures.
Créer un client
createEvmClient renvoie un ensemble de clients reposant sur viem. Il détecte automatiquement
l'identifiant de chaîne EVM via eth_chainId sauf si vous passez 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
Vous pouvez aussi passer directement rpcUrl (mutuellement exclusif avec endpoints), un
wsUrl / endpoints.evmWs pour le WebSocket (wss://evm-ws-testnet.qore.host sur le
testnet), un chainId explicite, et decimals
(par défaut 18, la convention EVM pour QOR — distincte de la base Cosmos uqor
de 10^6).
Dérivez un compte de signature EVM à partir d'une clé privée :
import { evmAccountFromPrivateKey } from "@qorechain/evm";
const account = evmAccountFromPrivateKey("0x...");
Assistants ERC-20
L'espace de noms erc20 (ainsi que les fonctions individuelles) encapsule les appels ERC-20 standard.
Les lectures prennent un client public viem ; les écritures prennent un client wallet.
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 brut est exporté sous le nom ERC20_ABI si vous préférez appeler viem directement.
Contrats
Wrappers génériques de déploiement et d'appel :
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 });
Fenêtre d'autorisation EVM (depuis la chaîne v3.2.0)
Depuis la version v3.2.0 de la chaîne (mainnet à partir du bloc 2,981,742, testnet à partir du bloc
5,920,000), la voie EVM n'admet une transaction que si elle provient d'un compte disposant d'une
clé ML-DSA-87 enregistrée et d'une fenêtre d'autorisation ouverte. Les lectures
(eth_call, soldes, reçus) et l'estimation du gas fonctionnent sans fenêtre, et les wallets
et bibliothèques tels que MetaMask, viem, ethers, Hardhat et Foundry signent comme avant ;
ce qui change, c'est que l'autorisation post-quantique voyage avant la
transaction, sous la forme d'un message de la voie Native signé de manière hybride. Les règles au niveau de la chaîne, les
bornes, les formes de la CLI et les codes de refus se trouvent dans
Fenêtre d'autorisation EVM.
Avec le SDK 0.8.2 ou ultérieur, vous pouvez ouvrir une fenêtre depuis le code (la 0.9.0
ajoute les options de portée ci-dessous). L'enregistrement de la clé
(une seule fois) est décrit dans Signature hybride ; l'exemple
ci-dessous ouvre ensuite une fenêtre pour un compte eth-natif unifié (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'ouverture d'une fenêtre fait avancer le nonce du compte (une seule identité : la séquence Cosmos
est le nonce EVM) ; lisez donc le nonce EVM après l'ouverture de la fenêtre et signez
alors la transaction EVM. maxValue borne la valeur plus les frais maximaux (limite de gas
multipliée par le plafond de frais) de chaque transaction : un transfert de 1,000 uqor avec 21,000 gas à
112.5 gwei consomme 3,363 uqor de la fenêtre. N'ouvrez une fenêtre que lorsque l'utilisateur
le demande ; n'en ouvrez jamais automatiquement.
Lorsque la voie EVM refuse une transaction, classifyEvmWindowRejection(err) vous
indique pourquoi :
try {
// send the EVM transaction (viem, ethers, ...)
} catch (err) {
const why = classifyEvmWindowRejection(err);
// "no-pqc-key" | "no-window" | "exhausted" | "invalid" | undefined
}
closeEvmWindowMsg construit le message de fermeture correspondant, et MAX_EVM_WINDOW_BLOCKS
ainsi que MAX_EVM_WINDOW_TXS exportent les bornes.
Restreindre la portée d'une fenêtre (depuis la chaîne v3.2.3, SDK 0.9.0)
Une fenêtre peut être restreinte à son ouverture : nativeOnly n'admet que les
transferts simples de QOR natif (pas de calldata, pas de création de contrat, pas de
destinataire qui porte du code, pas d'autorisation EIP-7702), et allowedTargets n'admet
que les transactions dont le destinataire figure parmi 16 adresses 0x listées au plus
(sans doublons ; la création de contrat est refusée). Ce sont deux nouveaux champs de
message : un nœud antérieur à la v3.2.3 refuse la transaction entière lorsque l'un des
deux est défini ; ne les définissez donc que sur un réseau qui a appliqué la v3.2.3 (les
deux réseaux publics l'ont fait). fetchEvmWindow relit les deux (nativeOnly,
allowedTargets ; ils valent false et vide avant la v3.2.3). Pour une fenêtre ouverte
uniquement pour envoyer du QOR, préférez nativeOnly. allowedTargets limite les contrats et jetons que la fenêtre peut toucher, pas le montant : un jeton listé admet n'importe quel montant, y compris approve, et un contrat listé peut déplacer tout ce que son code et ses approbations existantes permettent ; n'y listez donc pas de contrats génériques de transfert ou de routage. Une fenêtre ne borne que les transactions de la voie EVM (signées classiquement) ; les messages Cosmos signés avec la signature hybride PQC, tels que les appels cross-VM et authz, en sont exclus.
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",
);
Autres listes de périmètre (depuis la chaîne v3.2.8, SDK 0.14.0)
À partir de la chaîne v3.2.8 (le testnet depuis le 12 novembre 2026 ; le mainnet ne l'a pas
appliquée), une fenêtre peut porter trois listes de plus, que openEvmWindowMsg accepte à partir du SDK 0.14.0 :
validators (jusqu'à 16 adresses de contrats dont la vérification de la signature du compte compte pour
les propres actions du compte, comme un module de validateur ou un point d'entrée ERC-4337),
stakingValidators (des validateurs qorvaloper1... auxquels la fenêtre peut déléguer ou redéléguer
via le precompile de staking) et ibcReceivers (des destinataires ICS-20, chacun écrit
"<channel>/<receiver>"). Le constructeur vérifie le format et refuse les doublons avant que
quoi que ce soit soit signé. Ne les renseignez que sur un réseau qui exécute la v3.2.8 : un nœud antérieur refuse
le message. fetchEvmWindow ne renvoie pas ces trois listes, et la route REST de la fenêtre ne les renvoie pas non plus en v3.2.8 : conservez les valeurs avec lesquelles vous avez ouvert la fenêtre. Un appel renseignant les trois
listes a été exécuté sur le testnet le 12 novembre 2026 avec le SDK 0.14.0 et a réussi avec le code 0 (195,233 de gas utilisé) ; la
relecture REST a listé allowed_targets et n'a pas renvoyé les deux autres listes :
openEvmWindowMsg({
sender: account.address,
blocks: 7200,
maxTxs: 20,
maxValue: "1000000000",
allowedTargets: ["0x1111111111111111111111111111111111111111"], // your token contract
});
Pour le staking et pour la réclamation des récompenses, utilisez les messages Cosmos natifs (QoreX, ou les commandes staking et distribution de qorechaind) ; les champs de fenêtre ci-dessus décrivent ce que la chaîne accepte, mais staker depuis MetaMask n'est pas une voie prise en charge.
Voir la référence de la fenêtre EVM pour les règles.
Consentement EIP-7702 (depuis la chaîne v3.2.2, SDK 0.9.0)
Une transaction de type 4 (EIP-7702) n'est admise qu'après que chaque compte dont
l'autorisation prend effet a donné un consentement post-quantique à exactement ce
délégué, avec un MsgAuthorizeEVMDelegation signé en hybride. Le consentement est
consommé par la transaction qui installe la délégation et expire après les blocks que
vous avez définis (1 à 17,280) ; l'adresse zéro comme délégué consent à l'effacement. Le
SDK construit les messages et relit le consentement, y compris le nonce que le tuple
d'autorisation doit porter :
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) renvoie "no-consent" ou "invalid" lorsque la
voie EVM refuse une délégation. La requête de consentement nécessite la chaîne v3.2.2 ou
ultérieure. Les règles au niveau de la chaîne se trouvent dans
Délégations EIP-7702 ; les formes de la CLI
sont qorechaind tx pqc authorize-evm-delegation et clear-evm-delegation.
Les versions antérieures à la 0.9.0 ne construisent que la fenêtre sans portée (une fenêtre sans portée fonctionne toujours sur les deux réseaux) et n'ont aucun constructeur de consentement ; utilisez-y les formes de la CLI de Fenêtre d'autorisation EVM.
Précompilés
QoreChain expose des précompilés appelables par contrat à des adresses fixes. L'espace de noms
precompiles fournit des liaisons typées, et les adresses ainsi que les ABI sont
exportés.
Non actifs sur le mainnet ; trois sur le testnet. Les précompilés QoreChain sont compilés dans le nœud mais aucun n'est activé sur le mainnet (
qorechain-vladi). Sur le testnet (qorechain-diana), la listeactive_static_precompilescontient0x…0A01(vérification PQC),0x…0A02(statut de clé PQC) et0x…0C01(paramètres de consensus), vérifié le 27 octobre 2026 ; la paire d'IA (0x…0B01,0x…0B02) n'est active sur aucun des deux réseaux, et le pont inter-VM (0x…0901) n'était actif sur aucun des deux le 27 octobre (la liste du testnet le contenait aussi à partir du 4 novembre et le contenait toujours le 7 novembre 2026 ; sur le testnet, il est actif avec une liste d'autorisation et uneth_callen lecture seule a été testé le 7 novembre 2026 ; la liste du mainnet est vide). Un appel à une adresse inactive renvoie des données vides, de sorte que ces assistants lèvent une erreur. Voir Précompilés EVM : état du réseau.
| Précompilé | Fonction | Adresse |
|---|---|---|
| Pont inter-VM | (routage du pont) | 0x0000000000000000000000000000000000000901 |
| Vérification PQC | pqcVerify | 0x0000000000000000000000000000000000000a01 |
| Statut de clé PQC | pqcKeyStatus | 0x0000000000000000000000000000000000000a02 |
| Score de risque QCAI | aiRiskScore | 0x0000000000000000000000000000000000000b01 |
| Vérification d'anomalie QCAI | aiAnomalyCheck | 0x0000000000000000000000000000000000000b02 |
| Paramètres de consensus | 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);
Les ABI des précompilés sont exportés sous les noms IQORE_PQC_ABI, IQORE_AI_ABI, et
IQORE_CONSENSUS_ABI.
Lorsqu'un précompilé n'est pas actif (mainnet : tous ; testnet : la paire d'IA et le pont inter-VM), ou sur un nœud sans les précompilés QoreChain, ces appels lèvent une erreur « feature not present ». Gérez cela appel par appel.
Voir l'exemple evm-precompile pour une version exécutable.