إنتقل إلى المحتوى الرئيسي

دليل EVM

@qorechain/evm هو محوّل رقيق وآمن من حيث الأنواع فوق viem لمحرّك EVM في QoreChain. إنّه لا يعيد تنفيذ عميل EVM — فـ viem اعتمادية نظيرة. إنّه يضيف مصنع عميل مدركًا للسلسلة (مع كشف تلقائي لمعرّف سلسلة EVM)، ومساعدات ERC-20، وأغلفة نشر/استدعاء العقود، وارتباطات مُصنّفة لما قبل التجميع (precompiles) في EVM الخاص بـ QoreChain.

npm i @qorechain/evm viem

تعريفات السلسلة ومساعدات النافذة (0.12.0)​

تصدّر @qorechain/evm تعريفات سلسلة viem ‏qorechain (معرّف السلسلة 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 حدود السلسلة وتؤلّف الرسالة MsgOpenEVMWindow الخاصة بمسار Native لتوقيعها هجينةً، وتحدّد evmWindowCost وweiToUqorCeil حجم نافذة، وتحوّل toQorAddress / toEvmAddress حساب eth-native بين ترميزيه. كما تُنشر مساعدات النافذة بدون viem باسم @qorechain/evm/window. وصلت في الإصدار 0.11.0 (npm فقط) وهي موجودة في 0.12.0 وما بعده.

إنشاء عميل​

تُرجع createEvmClient حزمة عميل مدعومة بـ viem. تكشف تلقائيًا معرّف سلسلة EVM عبر eth_chainId ما لم تمرّر 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

يمكنك أيضًا تمرير rpcUrl مباشرةً (متعارض تبادليًا مع endpoints)، و wsUrl / endpoints.evmWs لـ WebSocket (wss://evm-ws-testnet.qore.host على شبكة الاختبار)، وchainId صريح، وdecimals (القيمة الافتراضية 18، وهي اصطلاح EVM لـ QOR — متمايز عن أساس Cosmos لـ uqor البالغ 10^6).

اشتقّ حساب توقيع EVM من مفتاح خاص:

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

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

مساعدات ERC-20​

يغلّف فضاء الأسماء erc20 (والدوال الفردية) استدعاءات ERC-20 القياسية. تأخذ عمليات القراءة عميل viem العام؛ وتأخذ عمليات الكتابة عميل محفظة.

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

يُصدَّر الـ ABI الخام باسم ERC20_ABI إن كنت تفضّل استدعاء viem مباشرةً.

العقود​

أغلفة نشر واستدعاء عامة:

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 كما كانت؛ الذي يتغير هو أن التفويض ما بعد الكمّي يسبق المعاملة، في صورة رسالة على المسار الأصلي (Native) موقَّعة توقيعًا هجينًا. القواعد على مستوى السلسلة والحدود وصيغ سطر الأوامر ورموز الرفض موجودة في نافذة تفويض EVM.

مع SDK 0.8.2 أو أحدث يمكنك فتح نافذة من الشيفرة (و0.9.0 تضيف خيارات النطاق أدناه). تسجيل المفتاح (مرة واحدة) موصوف في التوقيع الهجين؛ ثم يفتح المثال أدناه نافذة لحساب eth-native موحَّد (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

يؤدي فتح نافذة إلى تقدّم nonce الحساب (هوية واحدة: تسلسل Cosmos هو nonce في EVM)، لذا اقرأ nonce الخاص بـ EVM بعد فتح النافذة ووقّع معاملة EVM حينها. يحدّ maxValue القيمة زائد أقصى رسم (حد الغاز مضروبًا في سقف الرسوم) لكل معاملة: تحويل 1,000 uqor بغاز 21,000 وبسعر 112.5 gwei يستهلك 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 المعاملات التي يكون مستلمها واحدًا من عناوين 0x المدرجة وعددها 16 كحد أقصى (دون تكرار؛ ويُرفض إنشاء العقود). كلاهما حقلان جديدان في الرسالة: تُرفض المعاملة كلها في أي عقدة أقدم من v3.2.3 عند ضبط أيٍّ منهما، لذا اضبطهما فقط على شبكة طبّقت v3.2.3 (وقد طبّقتها الشبكتان العامتان). تقرأ fetchEvmWindow كليهما (nativeOnly و allowedTargets؛ وتُقرآن false وفارغتين قبل v3.2.3). وللنافذة التي تُفتح لإرسال QOR فقط، فضّل nativeOnly. يقيّد allowedTargets العقود والرموز التي قد تلمسها النافذة، لا المقدار: فالرمز المدرج يقبل أي مقدار منه، بما في ذلك approve، والعقد المدرج يستطيع نقل ما تسمح به شيفرته وموافقاته القائمة، لذا لا تُدرج عقود إعادة التوجيه أو الموجِّهات العامة. وتقيّد النافذة المعاملات على مسار EVM فقط (الموقَّعة تقليديًا)؛ أما رسائل Cosmos الموقَّعة بالتوقيع الهجين PQC، مثل استدعاءات cross-VM وauthz، فهي خارجها.

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 (شبكة الاختبار منذ 12 نوفمبر 2026؛ ولم تطبّقها الشبكة الرئيسية) يمكن أن تحمل النافذة ثلاث قوائم إضافية، تقبلها openEvmWindowMsg منذ SDK 0.14.0: validators (حتى 16 عنوان عقد يُعتدّ بتحقّقها من توقيع الحساب لإجراءات الحساب نفسه، مثل وحدة تحقق أو نقطة دخول ERC-4337)، وstakingValidators (مدققو qorvaloper1... الذين يجوز للنافذة التفويض أو إعادة التفويض إليهم عبر precompile التخزين) وibcReceivers (مستلمو ICS-20، يُكتب كل منهم "<channel>/<receiver>"). يفحص الباني الصيغة ويرفض التكرار قبل التوقيع بأي شيء. اضبطها فقط على شبكة تشغّل v3.2.8: فالعقدة الأقدم ترفض الرسالة. ولا تعيد fetchEvmWindow هذه القوائم الثلاث، ولا يعيدها مسار REST الخاص بالنافذة في v3.2.8 أيضًا: فاحتفظ بالقيم التي فتحت بها النافذة. شُغّل استدعاء يضبط القوائم الثلاث على شبكة الاختبار في 12 نوفمبر 2026 مع SDK 0.14.0 ونجح بالرمز 0 (الغاز المستخدم 195,233)؛ وسردت قراءة REST الحقل allowed_targets ولم تعد القائمتين الأخريين:

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

للتخزين (staking) والمطالبة بالمكافآت، استخدم رسائل Cosmos الأصلية (QoreX، أو أوامر qorechaind الخاصة بالتخزين والتوزيع)؛ فحقول النافذة أعلاه تصف ما تقبله السلسلة، لكن التخزين من MetaMask ليس مسارًا مدعومًا.

راجع مرجع نافذة تفويض EVM للقواعد.

لا تُقبل معاملة من النوع 4 (EIP-7702) إلا بعد أن يمنح كل حساب يسري تفويضه موافقة ما بعد كمّية على ذلك المفوَّض بالتحديد، عبر MsgAuthorizeEVMDelegation موقَّعة توقيعًا هجينًا. تُستهلك الموافقة بالمعاملة التي تثبّت التفويض، وتنتهي بعد عدد الكتل blocks الذي تضبطه (من 1 إلى 17,280)؛ والعنوان الصفري كمفوَّض يعني الموافقة على المسح. يبني الـ SDK الرسائل ويقرأ الموافقة، بما في ذلك الـ nonce الذي يجب أن تحمله مجموعة التفويض (authorisation tuple):

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) القيمة "no-consent" أو "invalid" عندما يرفض مسار EVM تفويضًا. يتطلب استعلام الموافقة السلسلة v3.2.2 أو أحدث. القواعد على مستوى السلسلة موجودة في تفويضات EIP-7702؛ وصيغ سطر الأوامر هي qorechaind tx pqc authorize-evm-delegation وclear-evm-delegation.

الإصدارات السابقة لـ 0.9.0 تبني النافذة غير المقيَّدة النطاق فقط (وما زالت النافذة غير المقيَّدة تعمل على الشبكتين) وليس فيها أي مُنشئ لرسائل الموافقة؛ استخدم هناك صيغ سطر الأوامر الواردة في نافذة تفويض EVM.

ما قبل التجميع (Precompiles)​

تعرّف QoreChain مكوّنات ما قبل التجميع القابلة للاستدعاء من العقود على عناوين ثابتة. يوفّر فضاء الأسماء precompiles ارتباطات مُصنّفة، وتُصدَّر العناوين وملفّات ABI.

غير مفعَّلة على الشبكة الرئيسية؛ وثلاثة منها مفعَّلة على شبكة الاختبار. مكوّنات ما قبل التجميع في QoreChain مُترجَمة داخل العقدة لكن أيًا منها غير مفعَّل على الشبكة الرئيسية (qorechain-vladi). وعلى شبكة الاختبار (qorechain-diana) تحوي القائمة active_static_precompiles العناوين 0x…0A01 (التحقق من PQC) و0x…0A02 (حالة مفتاح PQC) و0x…0C01 (معاملات الإجماع)، وفق الفحص في 27 أكتوبر 2026؛ أما زوج الذكاء الاصطناعي (0x…0B01 و0x…0B02) فغير مفعَّل على أي من الشبكتين، وجسر الآلات الافتراضية (0x…0901) لم يكن مفعَّلًا على أي منهما في 27 أكتوبر (واحتوته قائمة شبكة الاختبار أيضًا منذ 4 نوفمبر وما زالت في 7 نوفمبر 2026؛ وهو على شبكة الاختبار نشط مع قائمة سماح وجرى اختبار استدعاء eth_call للقراءة فقط في 7 نوفمبر 2026؛ وقائمة الشبكة الرئيسية فارغة). يعيد الاستدعاء إلى عنوان غير مفعَّل بيانات فارغة، لذا تُطلق تلك المساعدات أخطاءً. راجع مكوّنات EVM ما قبل التجميع: حالة الشبكة.

ما قبل التجميعالدالةالعنوان
جسر عبر-الأجهزة-الافتراضية (Cross-VM Bridge)(توجيه الجسر)0x0000000000000000000000000000000000000901
التحقق من PQCpqcVerify0x0000000000000000000000000000000000000a01
حالة مفتاح PQCpqcKeyStatus0x0000000000000000000000000000000000000a02
درجة مخاطر QCAIaiRiskScore0x0000000000000000000000000000000000000b01
فحص شذوذ QCAIaiAnomalyCheck0x0000000000000000000000000000000000000b02
معاملات الإجماعrlConsensusParams0x0000000000000000000000000000000000000c01
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.

حيث لا يكون مكوّن ما قبل التجميع مفعَّلًا (الشبكة الرئيسية: كلها؛ شبكة الاختبار: زوج الذكاء الاصطناعي وجسر الآلات الافتراضية)، أو على عقدة بلا مكوّنات ما قبل التجميع الخاصة بـ QoreChain، تُطلِق هذه الاستدعاءات خطأ "feature not present". عالج ذلك لكلّ استدعاء على حدة.

انظر مثال evm-precompile للحصول على نسخة قابلة للتشغيل.