EVM ガイド
@qorechain/evm は QoreChain EVM Engine 向けの、viem 上に構築された
薄く型安全なアダプターです。EVM クライアントを再実装するものではなく、viem はピア
依存です。チェーンを認識するクライアントファクトリ(EVM チェーン ID の
自動検出付き)、ERC-20 ヘルパー、コントラクトのデプロイ/呼び出しラッパー、QoreChain の
EVM プリコンパイル向けの型付きバインディングを追加します。
npm i @qorechain/evm viem
チェーン定義とウィンドウヘルパー(0.12.0)
@qorechain/evm は、viem のチェーン定義 qorechain(チェーン ID 9801)と
qorechainTestnet(9800)に加えて、QORECHAIN_CHAINS と QORECHAIN_REST_ENDPOINTS をエクスポートするため、
viem や wagmi のアプリで手書きする必要はありません。
import { createPublicClient, http } from "viem";
import { qorechainTestnet } from "@qorechain/evm";
const publicClient = createPublicClient({ chain: qorechainTestnet, transport: http() });
認可ウィンドウのヘルパーも含まれています。evmWindowStatus はアカウントのウィンドウを REST で読み取り、
openEvmWindowMessage はチェーンの上限を確認して、ハイブリッドで署名する Native レーンの MsgOpenEVMWindow を組み立てます。
evmWindowCost と weiToUqorCeil はウィンドウの規模を見積もり、toQorAddress / toEvmAddress は
eth-native アカウントを 2 つのエンコード間で変換します。ウィンドウヘルパーは、viem なしの
@qorechain/evm/window としても公開されています。これらは npm のみで公開された 0.11.0 で登場し、
0.12.0 以降に含まれています。
クライアントの作成
createEvmClient は viem を基盤としたクライアントバンドルを返します。chainId を
渡さない限り、eth_chainId を介して EVM チェーン ID を自動検出します。
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
rpcUrl を直接渡すこともできます(endpoints と相互排他)。WebSocket 用の
wsUrl / endpoints.evmWs(テストネットでは wss://evm-ws-testnet.qore.host)、明示的な chainId、decimals
(デフォルトは 18。これは QOR の EVM 上の慣例であり、Cosmos の uqor
基本単位 10^6 とは異なります)も渡せます。
秘密鍵から EVM 署名アカウントを導出します:
import { evmAccountFromPrivateKey } from "@qorechain/evm";
const account = evmAccountFromPrivateKey("0x...");
ERC-20 ヘルパー
erc20 名前空間(および個々の関数)は標準的な ERC-20 呼び出しをラップします。
読み取りは viem の public client を、書き込みは 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);
viem を直接呼び出したい場合のために、生の ABI が ERC20_ABI としてエクスポートされています。
コントラクト
汎用のデプロイおよび呼び出しラッパー:
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 認可ウィンドウ(チェーン v3.2.0)
チェーンバージョン v3.2.0(メインネットはブロック 2,981,742 から、テストネットはブロック
5,920,000 から)以降、EVM レーンは、登録済みの ML-DSA-87 鍵と開いている認可
ウィンドウを持つアカウントからのトランザクションのみを受け入れます。読み取り
(eth_call、残高、レシート)とガス見積もりはウィンドウなしでも動作し、MetaMask、
viem、ethers、Hardhat、Foundry などのウォレットやライブラリはこれまでどおり署名します。
変わるのは、ポスト量子の認可がトランザクションの前に、ハイブリッド署名された
ネイティブレーンのメッセージとして送られる点です。チェーンレベルのルール、上限、
CLI の形式、拒否コードは
EVM 認可ウィンドウにあります。
SDK 0.8.2 以降では、コードからウィンドウを開くことができます(下記のスコープオプションは
0.9.0 で追加されました)。鍵の登録(1 回のみ)は
ハイブリッド署名で説明しています。以下の例では、その後に
統合 eth ネイティブアカウント用のウィンドウを開きます(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
ウィンドウを開くとアカウントのノンスが進みます(アイデンティティは 1 つで、Cosmos の
シーケンスが EVM のノンスです)。そのため、EVM ノンスはウィンドウが開いた後に読み取り、
その時点で EVM トランザクションに署名してください。maxValue は、各トランザクションの
値と最大手数料(ガスリミット × 手数料上限)の合計を制限します。21,000 ガス、
112.5 gwei での 1,000 uqor の送金は、ウィンドウから 3,363 uqor を消費します。
ウィンドウを開くのは、ユーザーが求めたときだけにしてください。自動で開いてはいけません。
EVM レーンがトランザクションを拒否した場合、classifyEvmWindowRejection(err) が
その理由を教えてくれます:
try {
// send the EVM transaction (viem, ethers, ...)
} catch (err) {
const why = classifyEvmWindowRejection(err);
// "no-pqc-key" | "no-window" | "exhausted" | "invalid" | undefined
}
closeEvmWindowMsg は対応するクローズメッセージを構築し、MAX_EVM_WINDOW_BLOCKS と
MAX_EVM_WINDOW_TXS は上限をエクスポートします。
ウィンドウのスコープを絞る(チェーン v3.2.3、SDK 0.9.0)
ウィンドウは開くときに絞り込めます。nativeOnly はネイティブ QOR の通常の送金のみを受け付けます
(calldata なし、コントラクト作成なし、コードを持つ受取先なし、EIP-7702 認可なし)。
allowedTargets は、受取先が列挙された最大 16 個の 0x アドレス(重複なし)のいずれかである
トランザクションのみを受け付けます(コントラクト作成は拒否されます)。どちらも新しい
メッセージフィールドです。v3.2.3 未満のノードは、どちらかが設定されているとトランザクション全体を
拒否するため、v3.2.3 を適用済みのネットワークでのみ設定してください(両方の公開ネットワークが
適用済みです)。fetchEvmWindow は両方を読み戻します(nativeOnly、
allowedTargets。v3.2.3 より前は false と空になります)。QOR の送信のためだけに
開くウィンドウには、nativeOnly を推奨します。allowedTargets が制限するのは、ウィンドウが触れてよいコントラクトとトークンであり、金額ではありません。一覧に載せたトークンは、approve を含め任意の量を受け付け、一覧に載せたコントラクトは、そのコードと既存の承認が許す範囲のものをすべて動かせるため、汎用のフォワーダーやルーターのコントラクトを一覧に載せないでください。ウィンドウが制限するのは EVM レーン(古典署名)のトランザクションのみです。クロス VM 呼び出しや authz など、ハイブリッド PQC 署名で署名された Cosmos メッセージは、その対象外です。
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",
);
さらなるスコープのリスト(チェーン v3.2.8 以降、SDK 0.14.0)
チェーン v3.2.8 以降(テストネットは 2026年11月12日から。メインネットはまだ適用していません)では、
ウィンドウにさらに 3 つのリストを持たせることができ、openEvmWindowMsg は SDK 0.14.0 からそれらを受け付けます。
validators(アカウントの署名の検査が、アカウント自身の操作として有効と見なされるコントラクトアドレス。
バリデーターモジュールや ERC-4337 のエントリーポイントなど。最大 16 個)、
stakingValidators(ウィンドウがステーキングプリコンパイル経由で委任または再委任できる
qorvaloper1... のバリデーター)、ibcReceivers(ICS-20 の受取人。それぞれ
"<channel>/<receiver>" の形式で記述)です。ビルダーは、署名の前に形式を検査し、重複を拒否します。
設定するのは v3.2.8 を実行しているネットワークだけにしてください。それより下のノードはメッセージを拒否します。
fetchEvmWindow はこの 3 つのリストを返さず、v3.2.8 では REST のウィンドウ用ルートも返しません。ウィンドウを開いたときに指定した値を手元に保管してください。3 つのリストをすべて設定した呼び出しを、2026年11月12日にテストネットで SDK 0.14.0 を使って実行し、
コード 0 で成功しました(使用ガス 195,233)。REST の読み戻しには allowed_targets が含まれ、
ほかの 2 つのリストは返されませんでした:
openEvmWindowMsg({
sender: account.address,
blocks: 7200,
maxTxs: 20,
maxValue: "1000000000",
allowedTargets: ["0x1111111111111111111111111111111111111111"], // your token contract
});
ステーキングと報酬の請求には、ネイティブのCosmosメッセージ(QoreX、またはqorechaindのstakingおよびdistributionコマンド)を使用してください。上記のウィンドウのフィールドは、チェーンが受け付ける内容を示すもので、MetaMaskからのステーキングはサポートされていません。
ルールについては EVM ウィンドウリファレンス を参照してください。
EIP-7702 の同意(チェーン v3.2.2、SDK 0.9.0)
type-4(EIP-7702)トランザクションは、認可が有効になるすべてのアカウントが、まさにその委任先に対して
ポスト量子の同意を、ハイブリッド署名された MsgAuthorizeEVMDelegation で与えた後にのみ
受け付けられます。同意は、委任をインストールするトランザクションによって使い切られ、設定した
blocks(1 から 17,280)の経過後に失効します。委任先としてゼロアドレスを指定すると、解除への
同意になります。SDK はメッセージを構築し、認可タプルが持つべき nonce を含めて、同意を
読み戻します:
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) は、EVM レーンが委任を拒否した場合に "no-consent" または
"invalid" を返します。同意クエリにはチェーン v3.2.2 以降が必要です。チェーンレベルの
ルールは
EIP-7702 の委任にあります。CLI の形式は
qorechaind tx pqc authorize-evm-delegation と clear-evm-delegation です。
0.9.0 より前のリリースはスコープなしのウィンドウしか構築できず(スコープなしのウィンドウは 両ネットワークで引き続き動作します)、同意ビルダーもありません。その場合は EVM 認可ウィンドウの CLI の形式を使用してください。
プリコンパイル
QoreChain は固定アドレスでコントラクトから呼び出し可能なプリコンパイルを公開しています。
precompiles 名前空間が型付きバインディングを提供し、アドレスと ABI が
エクスポートされています。
メインネットでは有効ではなく、テストネットでは 3 つが有効です。 QoreChain の プリコンパイルはノードにコンパイルされていますが、メインネット(
qorechain-vladi)では どれも有効化されていません。テストネット(qorechain-diana)では、active_static_precompilesのリストに0x…0A01(PQC 検証)、0x…0A02(PQC 鍵ステータス)、0x…0C01(コンセンサスパラメータ)が含まれています(2026年10月27日に確認)。AI の 2 つ (0x…0B01、0x…0B02)は、どちらのネットワークでも有効ではなく、クロス VM ブリッジ(0x…0901)は 10月27日にはどちらでも有効ではありませんでした(テストネットのリストには 11月4日からも含まれており、2026年11月7日にも含まれていました。テストネットでは許可リスト付きで有効であり、2026年11月7日に読み取り専用のeth_callがテストされました。メインネットのリストは空です)。有効でないアドレスへの呼び出しは空のデータを返すため、それらの ヘルパーはスローします。 EVM プリコンパイル: ネットワークステータスを参照してください。
| プリコンパイル | 関数 | アドレス |
|---|---|---|
| Cross-VM Bridge | (ブリッジルーティング) | 0x0000000000000000000000000000000000000901 |
| PQC verify | pqcVerify | 0x0000000000000000000000000000000000000a01 |
| PQC key status | pqcKeyStatus | 0x0000000000000000000000000000000000000a02 |
| QCAI risk score | aiRiskScore | 0x0000000000000000000000000000000000000b01 |
| QCAI anomaly check | aiAnomalyCheck | 0x0000000000000000000000000000000000000b02 |
| Consensus params | 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 は IQORE_PQC_ABI、IQORE_AI_ABI、
IQORE_CONSENSUS_ABI としてエクスポートされています。
プリコンパイルが有効でない場合(メインネット: すべて。テストネット: AI の 2 つと クロス VM ブリッジ)、または QoreChain プリコンパイルを持たないノードでは、これらの呼び出しは「feature not present」エラーをスローします。呼び出しごとに処理してください。
実行可能なバージョンについては evm-precompile サンプルを参照してください。