Zum Hauptinhalt springen

EVM-Leitfaden

@qorechain/evm ist ein schlanker, typsicherer Adapter über viem für die QoreChain EVM Engine. Er implementiert keinen EVM-Client neu — viem ist eine Peer- Abhängigkeit. Er ergänzt eine chain-bewusste Client-Factory (mit automatischer Erkennung der EVM-Chain-ID), ERC-20-Helfer, Wrapper zum Deployen/Aufrufen von Verträgen sowie typisierte Bindings für QoreChains EVM-Precompiles.

npm i @qorechain/evm viem

Chain-Definitionen und Fenster-Helfer (0.12.0)​

@qorechain/evm exportiert die viem-Chain-Definitionen qorechain (Chain-ID 9801) und qorechainTestnet (9800) sowie QORECHAIN_CHAINS und QORECHAIN_REST_ENDPOINTS, sodass eine viem- oder wagmi-App sie nicht von Hand schreiben muss:

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

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

Er enthält außerdem die Helfer für das Autorisierungsfenster: evmWindowStatus liest das Fenster eines Kontos über REST, openEvmWindowMessage prüft die Grenzen der Chain und setzt das MsgOpenEVMWindow der Native-Lane zusammen, das hybrid zu signieren ist, evmWindowCost und weiToUqorCeil bemessen ein Fenster, und toQorAddress / toEvmAddress wandeln ein eth-native-Konto zwischen seinen beiden Kodierungen um. Die Fenster-Helfer werden auch ohne viem als @qorechain/evm/window veröffentlicht. Sie kamen mit dem nur auf npm veröffentlichten 0.11.0 und sind in 0.12.0 und später enthalten.

Einen Client erstellen​

createEvmClient gibt ein Client-Bundle zurück, das von viem unterstützt wird. Es erkennt die EVM-Chain-ID automatisch über eth_chainId, sofern Sie nicht chainId übergeben.

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

Sie können auch rpcUrl direkt übergeben (gegenseitig ausschließend mit endpoints), eine wsUrl / endpoints.evmWs für WebSocket (wss://evm-ws-testnet.qore.host im Testnet), eine explizite chainId sowie decimals (Standardwert 18, die EVM-Konvention für QOR — abweichend von der Cosmos-Basis uqor von 10^6).

Leiten Sie ein EVM-Signaturkonto aus einem privaten Schlüssel ab:

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

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

ERC-20-Helfer​

Der erc20-Namespace (sowie die einzelnen Funktionen) kapseln standardmäßige ERC-20-Aufrufe. Lesezugriffe benötigen einen viem-Public-Client; Schreibzugriffe einen 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);

Die rohe ABI wird als ERC20_ABI exportiert, falls Sie viem lieber direkt aufrufen möchten.

Verträge​

Generische Wrapper zum Deployen und Aufrufen:

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 });

EVM-Autorisierungsfenster (seit Chain v3.2.0)​

Seit Chain-Version v3.2.0 (Mainnet ab Block 2.981.742, Testnet ab Block 5.920.000) lässt die EVM-Lane eine Transaktion nur von einem Konto zu, das einen registrierten ML-DSA-87-Schlüssel und ein offenes Autorisierungsfenster hat. Lesezugriffe (eth_call, Guthaben, Receipts) und Gasschätzung funktionieren ohne beides, und Wallets und Bibliotheken wie MetaMask, viem, ethers, Hardhat und Foundry signieren wie bisher; neu ist, dass die Post-Quantum-Autorisierung der Transaktion vorausgeht, und zwar als hybrid-signierte Native-Lane-Nachricht. Die Regeln auf Chain-Ebene, die Grenzwerte, die CLI-Formen und die Ablehnungscodes stehen unter EVM-Autorisierungsfenster.

Mit SDK 0.8.2 oder neuer können Sie ein Fenster aus Code heraus öffnen (0.9.0 ergänzt die unten beschriebenen Scope-Optionen). Das (einmalige) Registrieren des Schlüssels ist unter Hybrides Signieren beschrieben; das folgende Beispiel öffnet dann ein Fenster für ein vereinheitlichtes eth-natives Konto (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

Das Öffnen eines Fensters erhöht die Nonce des Kontos (eine Identität: die Cosmos-Sequence ist die EVM-Nonce). Lesen Sie die EVM-Nonce daher nach dem Öffnen des Fensters und signieren Sie die EVM-Transaktion erst dann. maxValue begrenzt den Wert plus die maximale Gebühr (Gaslimit mal Fee-Cap) jeder Transaktion: Ein Transfer von 1.000 uqor mit 21.000 Gas bei 112,5 gwei verbraucht 3.363 uqor des Fensters. Öffnen Sie ein Fenster nur, wenn der Nutzer es verlangt; öffnen Sie nie automatisch eines.

Wenn die EVM-Lane eine Transaktion ablehnt, sagt Ihnen classifyEvmWindowRejection(err) warum:

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

closeEvmWindowMsg baut die passende Schließen-Nachricht, und MAX_EVM_WINDOW_BLOCKS sowie MAX_EVM_WINDOW_TXS exportieren die Grenzwerte.

Ein Fenster einschränken (seit Chain v3.2.3, SDK 0.9.0)​

Ein Fenster kann beim Öffnen eingeschränkt werden: nativeOnly lässt nur einfache Transfers von nativem QOR zu (keine Calldata, keine Vertragserstellung, keinen Empfänger, der Code trägt, keine EIP-7702-Autorisierung), und allowedTargets lässt nur Transaktionen zu, deren Empfänger eine von bis zu 16 aufgelisteten 0x-Adressen ist (keine Duplikate; die Vertragserstellung wird abgelehnt). Beides sind neue Nachrichtenfelder: Ein Node unterhalb von v3.2.3 lehnt die gesamte Transaktion ab, wenn eines davon gesetzt ist; setzen Sie sie daher nur in einem Netzwerk, das v3.2.3 angewendet hat (beide öffentlichen Netzwerke haben das). fetchEvmWindow liest beide zurück (nativeOnly, allowedTargets; vor v3.2.3 lesen sie sich als false und leer). Für ein Fenster, das nur zum Senden von QOR geöffnet wird, bevorzugen Sie nativeOnly. allowedTargets begrenzt, welche Contracts und Tokens das Fenster berühren darf, nicht wie viel: Ein aufgeführtes Token lässt jeden Betrag davon zu, einschließlich approve, und ein aufgeführter Contract kann alles bewegen, was sein Code und bestehende Genehmigungen erlauben; führen Sie daher keine generischen Forwarder- oder Router-Contracts auf. Ein Fenster begrenzt nur Transaktionen auf der EVM-Lane (klassisch signiert); Cosmos-Nachrichten, die mit der hybriden PQC-Signatur signiert sind, wie Cross-VM-Aufrufe und authz, liegen außerhalb davon.

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",
);

Weitere Scope-Listen (seit Chain v3.2.8, SDK 0.14.0)​

Ab Chain v3.2.8 (das Testnet seit dem 12. November 2026; das Mainnet hat sie nicht angewendet) kann ein Fenster drei weitere Listen tragen, die openEvmWindowMsg ab SDK 0.14.0 entgegennimmt: validators (bis zu 16 Contract-Adressen, deren Prüfung der Signatur des Kontos für die eigenen Aktionen des Kontos zählt, etwa ein Validator-Modul oder ein ERC-4337-Entry-Point), stakingValidators (qorvaloper1...-Validatoren, an die das Fenster über den Staking-Precompile delegieren oder umdelegieren darf) und ibcReceivers (ICS-20-Empfänger, jeweils als "<channel>/<receiver>" geschrieben). Der Builder prüft das Format und lehnt Duplikate ab, bevor etwas signiert wird. Setzen Sie sie nur in einem Netzwerk, das v3.2.8 betreibt: Ein Node darunter lehnt die Nachricht ab. fetchEvmWindow liefert diese drei Listen nicht, und die REST-Fensterroute liefert sie in v3.2.8 ebenfalls nicht: Behalten Sie die Werte, mit denen Sie das Fenster geöffnet haben. Ein Aufruf, der alle drei Listen setzte, wurde am 12. November 2026 mit SDK 0.14.0 im Testnet ausgeführt und war mit Code 0 erfolgreich (195,233 Gas verbraucht); das REST-Zurücklesen listete allowed_targets und lieferte die anderen beiden Listen nicht:

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

Für Staking und für das Einfordern von Belohnungen verwenden Sie die nativen Cosmos-Nachrichten (QoreX oder die qorechaind-Befehle für Staking und Distribution); die Fensterfelder oben beschreiben, was die Chain akzeptiert, aber Staking aus MetaMask ist kein unterstützter Weg.

Die Regeln stehen in der EVM-Fensterreferenz.

Eine Typ-4-Transaktion (EIP-7702) wird erst zugelassen, nachdem jedes Konto, dessen Autorisierung wirksam wird, mit einer hybrid-signierten MsgAuthorizeEVMDelegation eine Post-Quanten-Einwilligung genau für diesen Delegate erteilt hat. Die Einwilligung wird von der Transaktion verbraucht, die die Delegation installiert, und läuft nach den von Ihnen festgelegten blocks ab (1 bis 17.280); die Nulladresse als Delegate willigt in das Löschen ein. Das SDK baut die Nachrichten und liest die Einwilligung zurück, einschließlich der Nonce, die das Autorisierungs-Tupel tragen muss:

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) liefert "no-consent" oder "invalid", wenn die EVM-Lane eine Delegation ablehnt. Die Einwilligungsabfrage erfordert Chain v3.2.2 oder neuer. Die Regeln auf Chain-Ebene stehen unter EIP-7702-Delegationen; die CLI-Formen lauten qorechaind tx pqc authorize-evm-delegation und clear-evm-delegation.

Releases vor 0.9.0 bauen nur das Fenster ohne Scope (ein Fenster ohne Scope funktioniert weiterhin auf beiden Netzwerken) und haben keine Einwilligungs-Builder; verwenden Sie dort die CLI-Formen unter EVM-Autorisierungsfenster.

Precompiles​

QoreChain definiert vertragsaufrufbare Precompiles an festen Adressen. Der precompiles-Namespace bietet typisierte Bindings, und die Adressen sowie ABIs werden exportiert.

Im Mainnet nicht aktiv; drei im Testnet. Die QoreChain-Precompiles sind in den Node einkompiliert, aber keines ist im Mainnet (qorechain-vladi) aktiviert. Im Testnet (qorechain-diana) enthält die Liste active_static_precompiles 0x…0A01 (PQC verify), 0x…0A02 (PQC key status) und 0x…0C01 (consensus params), geprüft am 27. Oktober 2026; das KI-Paar (0x…0B01, 0x…0B02) ist in keinem der beiden Netzwerke aktiv, und die Cross-VM-Bridge (0x…0901) war es am 27. Oktober in keinem von beiden (die Testnet-Liste enthielt sie auch seit dem 4. November und am 7. November 2026 weiterhin; im Testnet ist es mit einer Allowlist aktiv, und am 7. November 2026 wurde ein schreibgeschützter eth_call getestet; die Liste des Mainnets ist leer). Ein Aufruf an eine inaktive Adresse liefert leere Daten zurück, sodass diese Helfer Fehler werfen. Siehe EVM-Precompiles: Netzwerkstatus.

PrecompileFunktionAdresse
Cross-VM Bridge(Bridge-Routing)0x0000000000000000000000000000000000000901
PQC verifypqcVerify0x0000000000000000000000000000000000000a01
PQC key statuspqcKeyStatus0x0000000000000000000000000000000000000a02
QCAI risk scoreaiRiskScore0x0000000000000000000000000000000000000b01
QCAI anomaly checkaiAnomalyCheck0x0000000000000000000000000000000000000b02
Consensus paramsrlConsensusParams0x0000000000000000000000000000000000000c01
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);

Die Precompile-ABIs werden als IQORE_PQC_ABI, IQORE_AI_ABI und IQORE_CONSENSUS_ABI exportiert.

Wo ein Precompile nicht aktiv ist (Mainnet: alle; Testnet: das KI-Paar und die Cross-VM-Bridge) oder auf einem Node ohne die QoreChain-Precompiles, werfen diese Aufrufe einen Fehler "feature not present". Behandeln Sie dies pro Aufruf.

Eine lauffähige Version finden Sie im evm-precompile-Beispiel.