Aller au contenu principal

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.

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 liste active_static_precompiles contient 0x…0A01 (vérification PQC), 0x…0A02 (statut de clé PQC) et 0x…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 un eth_call en 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éFonctionAdresse
Pont inter-VM(routage du pont)0x0000000000000000000000000000000000000901
Vérification PQCpqcVerify0x0000000000000000000000000000000000000a01
Statut de clé PQCpqcKeyStatus0x0000000000000000000000000000000000000a02
Score de risque QCAIaiRiskScore0x0000000000000000000000000000000000000b01
Vérification d'anomalie QCAIaiAnomalyCheck0x0000000000000000000000000000000000000b02
Paramètres de consensusrlConsensusParams0x0000000000000000000000000000000000000c01
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.