Skip to main content

EVM guide

@qorechain/evm is a thin, type-safe adapter over viem for the QoreChain EVM Engine. It does not reimplement an EVM client — viem is a peer dependency. It adds a chain-aware client factory (with EVM chain-id auto-detection), ERC-20 helpers, contract deploy/call wrappers, and typed bindings for QoreChain's EVM precompiles.

npm i @qorechain/evm viem

Chain definitions and window helpers (0.12.0)​

@qorechain/evm exports the viem chain definitions qorechain (chain id 9801) and qorechainTestnet (9800), plus QORECHAIN_CHAINS and QORECHAIN_REST_ENDPOINTS, so a viem or wagmi app does not hand-write them:

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

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

It also has the authorization window helpers: evmWindowStatus reads an account's window over REST, openEvmWindowMessage checks the chain's bounds and composes the Native-lane MsgOpenEVMWindow to sign hybrid, evmWindowCost and weiToUqorCeil size a window, and toQorAddress / toEvmAddress convert an eth-native account between its two encodings. The window helpers are also published without viem as @qorechain/evm/window. They arrived in the npm-only 0.11.0 and are in 0.12.0 and later.

Create a client​

createEvmClient returns a client bundle backed by viem. It auto-detects the EVM chain id via eth_chainId unless you pass 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

You can also pass rpcUrl directly (mutually exclusive with endpoints), a wsUrl / endpoints.evmWs for WebSocket (wss://evm-ws-testnet.qore.host on the testnet), an explicit chainId, and decimals (defaults to 18, the EVM convention for QOR — distinct from the Cosmos uqor base of 10^6).

Derive an EVM signing account from a private key:

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

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

ERC-20 helpers​

The erc20 namespace (and the individual functions) wrap standard ERC-20 calls. Reads take a viem public client; writes take a 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);

The raw ABI is exported as ERC20_ABI if you prefer to call viem directly.

Contracts​

Generic deploy and call wrappers:

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 authorization window (since chain v3.2.0)​

Since chain version v3.2.0 (mainnet from block 2,981,742, testnet from block 5,920,000) the EVM lane admits a transaction only from an account that has a registered ML-DSA-87 key and an open authorization window. Reads (eth_call, balances, receipts) and gas estimation work without one, and wallets and libraries such as MetaMask, viem, ethers, Hardhat and Foundry sign as before; what changes is that the post-quantum authorization travels ahead of the transaction, as a hybrid-signed Native-lane message. The chain-level rules, the bounds, the CLI forms and the refusal codes are in EVM authorisation window.

With SDK 0.8.2 or later you can open a window from code (0.9.0 adds the scope options below). Registering the key (once) is described in Hybrid signing; the example below then opens a window for a unified eth-native account (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

Opening a window advances the account's nonce (one identity: the Cosmos sequence is the EVM nonce), so read the EVM nonce after the window is open and sign the EVM transaction then. maxValue bounds value plus the maximum fee (gas limit times fee cap) of each transaction: a 1,000 uqor transfer with 21,000 gas at 112.5 gwei consumes 3,363 uqor of the window. Open a window only when the user asks for it; never open one automatically.

When the EVM lane refuses a transaction, classifyEvmWindowRejection(err) tells you why:

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

closeEvmWindowMsg builds the matching close message, and MAX_EVM_WINDOW_BLOCKS and MAX_EVM_WINDOW_TXS export the bounds.

Scope a window (since chain v3.2.3, SDK 0.9.0)​

A window can be narrowed when it is opened: nativeOnly admits plain transfers of native QOR only (no calldata, no contract creation, no recipient that carries code, no EIP-7702 authorisation), and allowedTargets admits only transactions whose recipient is one of up to 16 listed 0x addresses (no duplicates; contract creation is refused). Both are new message fields: a node below v3.2.3 refuses the whole transaction when either is set, so set them only on a network that has applied v3.2.3 (both public networks have). fetchEvmWindow reads both back (nativeOnly, allowedTargets; they read false and empty before v3.2.3). For a window opened only to send QOR, prefer nativeOnly. allowedTargets limits which contracts and tokens the window may touch, not how much: a listed token admits any amount of it, including approve, and a listed contract can move whatever its code and existing approvals allow, so do not list generic forwarder or router contracts. A window bounds only transactions on the EVM lane (classically signed); Cosmos messages signed with the hybrid PQC signature, such as cross-VM calls and authz, are outside it.

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

More scope lists (since chain v3.2.8, SDK 0.14.0)​

From chain v3.2.8 (the testnet since 12 November 2026; mainnet has not applied it) a window can carry three more lists, which openEvmWindowMsg accepts from SDK 0.14.0: validators (up to 16 contract addresses whose check of the account's signature counts for the account's own actions, such as a validator module or an ERC-4337 entry point), stakingValidators (qorvaloper1... validators the window may delegate or redelegate to through the staking precompile) and ibcReceivers (ICS-20 receivers, each written "<channel>/<receiver>"). The builder checks the format and refuses duplicates before anything is signed. Set them only on a network that runs v3.2.8: a node below it refuses the message. fetchEvmWindow does not return these three lists, and the REST window route does not return them either in v3.2.8: keep the values you opened the window with. A call setting all three lists was run on the testnet on 12 November 2026 with SDK 0.14.0 and succeeded with code 0 (195,233 gas used); the REST read-back listed allowed_targets and did not return the other two lists:

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

For staking and for claiming rewards, use the native Cosmos messages (QoreX, or the qorechaind staking and distribution commands); the window fields above describe what the chain accepts, but staking from MetaMask is not a supported path.

See the EVM window reference for the rules.

A type-4 (EIP-7702) transaction is admitted only after every account whose authorisation takes effect has given a post-quantum consent to exactly that delegate, with a hybrid-signed MsgAuthorizeEVMDelegation. The consent is used up by the transaction that installs the delegation and expires after the blocks you set (1 to 17,280); the zero address as the delegate consents to clearing. The SDK builds the messages and reads the consent back, including the nonce the authorisation tuple must carry:

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) returns "no-consent" or "invalid" when the EVM lane refuses a delegation. The consent query needs chain v3.2.2 or later. The chain-level rules are in EIP-7702 delegations; the CLI forms are qorechaind tx pqc authorize-evm-delegation and clear-evm-delegation.

Releases before 0.9.0 build only the unscoped window (an unscoped window still works on both networks) and have no consent builders; use the CLI forms in EVM authorisation window there.

Precompiles​

QoreChain defines contract-callable precompiles at fixed addresses. The precompiles namespace provides typed bindings, and the addresses and ABIs are exported.

Not active on mainnet; three on the testnet. The QoreChain precompiles are compiled into the node but none is activated on mainnet (qorechain-vladi). On the testnet (qorechain-diana) the active_static_precompiles list holds 0x…0A01 (PQC verify), 0x…0A02 (PQC key status) and 0x…0C01 (consensus params), checked 27 October 2026; the AI pair (0x…0B01, 0x…0B02) is not active on either network, and the cross-VM bridge (0x…0901) was not active on either on 27 October (the testnet list also held it from 4 November and still did on 7 November 2026; on the testnet it is active with an allowlist and a read-only eth_call was tested on 7 November 2026; mainnet's list is empty). A call to an inactive address returns empty data, so those helpers throw. See EVM Precompiles: Network status.

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

The precompile ABIs are exported as IQORE_PQC_ABI, IQORE_AI_ABI, and IQORE_CONSENSUS_ABI.

Where a precompile is not active (mainnet: all of them; testnet: the AI pair and the cross-VM bridge), or on a node without the QoreChain precompiles, these calls throw a "feature not present" error. Handle that per-call.

See the evm-precompile example for a runnable version.