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

تكاملات QoreX (@qorechain/qorex-*)

تكاملات QoreX هي ست حزم npm صغيرة لمطوري dApp الذين يريدون أن تعمل محفظة QoreX في واجهة أمامية على EVM أو Cosmos أو Solana، وللفرق التي تختبر هذه الواجهات. ثلاث منها موصّلات محافظ لمكتبات شائعة (RainbowKit وInterchain Kit وcosmos-kit)، وواحدة تحوي الأنواع المشتركة ودوال الاكتشاف، واثنتان أدوات اختبار (محفظة وهمية وتجهيزات Playwright). جميعها بالإصدار 0.1.0، نُشرت في 27 أكتوبر 2026، بترخيص Apache-2.0.

ما لا تفعله: فهي لا تحتفظ بالمفاتيح، ولا تجعل QoreX أكثر مما هو عليه اليوم. اقرأ الحدود والمشكلات المعروفة قبل أن تبني عليها: فإصدارات المتاجر الحيّة من QoreX تدعم جزءًا مما يمكن ربط هذه الحزم به، والحدود مذكورة هناك.

الابتكارات​

  • اكتشاف لا يمكن أن يختار المحفظة الخطأ. تعلن QoreX عن نفسها عبر EIP-6963 بالاسم المعكوس للنطاق network.qore.qorex ولا تكتب أبدًا في window.ethereum. تختار @qorechain/qorex-types المزوّد بهذا الاسم وحده، وتثبّت محفظة RainbowKit الموصّل على المزوّد المُعلَن ولا تعود أبدًا إلى window.ethereum.
  • المحفظة هي من تبني التوقيع الهجين، والصفحة لا تحمل أبدًا المفتاح ما بعد الكمّي. يحتاج المسار الأصلي لـ QoreChain إلى توقيع secp256k1 إضافة إلى توقيع ML-DSA-87 (FIPS 204). على المزوّد الأصلي (window.qorex.native) تسلّم الدعوة signAndBroadcast الرسائل إلى QoreX، التي تبني المعاملة وتوقّعها بالمفتاحين وتبثّها. والنتيجة هي txHash وcode وheight وshield، حيث تكون shield هي shielded متى حملت المعاملة المثبَّتة الطبقة الهجينة.
  • فحوصات القدرات بدل فحوصات الإصدار. تقرأ الحزم قائمة capabilities الخاصة بالمحفظة (hasCapability)، فتُكتشف ميزة مثل signAndBroadcast ولا تُخمَّن من رقم إصدار.
  • الرفض صريح، برموز ثابتة. يُرفض توقيع Amino عمدًا، لأن Amino JSON لا يستطيع حمل التوقيع الهجين؛ وترمي الموصّلات QorexIntegrationError برموز مثل QOREX_AMINO_REFUSED وQOREX_USE_SIGN_AND_BROADCAST وQOREX_NOT_SUPPORTED_YET، وتفحصها isQorexIntegrationError(err, code).
  • بديل اختباري يوقّع فعلًا. تحقن @qorechain/qorex-wallet-mock الكائنات نفسها التي تحقنها QoreX (window.qorex = { evm, native, svm })، وتسجّل محفظة Solana، وتوقّع بالخوارزميات الحقيقية (ML-DSA-87 الهجين عبر QoreSign على المسار الأصلي، وsecp256k1 على EVM، وed25519 على Solana) انطلاقًا من العبارة الاختبارية العامة على الشبكة التجريبية افتراضيًا. وتعلن عن نفسها باسم network.qore.qorex.mock، فلا يستطيع الكود الذي يختار QoreX بصرامة أن يخلطها بالمحفظة.
  • ملفّا سلوك. يتصرف الملف current في المحاكاة كما تتصرف QoreX الحيّة اليوم؛ ويضيف planned ما أعلن عنه فريق QoreX، فتبني مسبقًا دون أن تدّعي المحاكاة شيئًا لا تفعله المحفظة بعد.
  • تجهيزات Playwright على طراز Synpress v4 (qorexMockFixtures) تحقن المحاكاة قبل التنقل، فلا يحتاج اختبار شامل (end-to-end) إلى إضافة متصفح.
  • حسابات تقودها المحفظة دون أحداث. لأن QoreX لا تُصدر accountsChanged ولا chainChanged بعد، تتضمن محفظة RainbowKit خيارًا اختياريًا pollAccountsOnFocus يعيد قراءة eth_accounts وeth_chainId عندما تستعيد الصفحة التركيز.

ما تُستخدم من أجله​

  1. dApp على wagmi وRainbowKit يضيف QoreX. أضف qorexWallet إلى قائمة محافظ RainbowKit وQOREX_CHAINS إلى إعداد wagmi. يتصل المستخدمون الذين لديهم QoreX ويقرأ الـ dApp عنوانهم 0x ومعرّف السلسلة (9801 أو 9800). أما من لا يملك QoreX فيرى روابط المتاجر.
  2. dApp على Cosmos باستخدام Interchain Kit أو cosmos-kit يضيف QoreX. أضف محفظة QoreX إلى ChainProvider وأرسل معاملات QoreChain بـ qorexSignAndBroadcast: تبني QoreX المعاملة وتضيف التوقيع الهجين وتبثّها، لأن الصفحة لا تستطيع حمل مفتاح ML-DSA-87.
  3. dApp يدعم Keplr أصلًا. يتبع window.qorex.native نمط Keplr (enable وgetKey وsignDirect)، فالتكامل بضعة أسطر. ويسرد دليل المستودع كل فرق.
  4. اختبارات CI لتدفقات المحفظة دون إضافة. يشغّل فريق الجودة Playwright بـ qorexMockFixtures({ profile: "current" })، وينقر Connect ويؤكد أن الصفحة تعرض qorex.addresses.evm. وتختبر qorex.rejectNext() مسار الرفض.
  5. البناء مسبقًا لميزات QoreX الجديدة. شغّل المجموعة نفسها بـ profile: "planned" لتجريب الميزات المعلن عنها (توقيع EVM وأحداث تغيّر الحساب وإضافة signDirect للطبقة الهجينة) قبل أن تصدرها QoreX.
  6. اختبار بثّ حقيقي على الشبكة التجريبية. بعبارة استعادة تجريبية ممولة خاصة بها، يدع الفريق المحاكاة تنفّذ signAndBroadcast لمعاملة موقّعة هجينًا إلى qorechain-diana ويفحص النتيجة في الصفحة.
  7. اكتشاف الميزات بدل فحص الإصدار. يعرض dApp زر إرسال على QoreChain عندما تكون hasCapability(native, "signAndBroadcast") صحيحة، فتفعّل إصدارات QoreX الجديدة الميزات دون تغيير في الـ dApp.

كيف تعمل​

  • مسار EVM. لا تكتب QoreX أبدًا في window.ethereum. تعلن عن مزوّد EIP-1193 عبر EIP-6963 بالاسم المعكوس للنطاق network.qore.qorex؛ وتختار qorexWallet() وdiscoverQorexEip1193() هذا المزوّد بالضبط. الكائن نفسه موجود أيضًا في window.qorex.evm.
  • المسار الأصلي. ‏window.qorex.native مزوّد بنمط Keplr (وليس اسمًا بديلًا لـ window.keplr). تتطلب QoreChain توقيعًا هجينًا secp256k1 زائد ML-DSA-87 على معاملات المسار الأصلي، ولا يحمل مفتاح ML-DSA-87 إلا المحفظة، ولذلك يرسل الـ dApp الرسائل إلى signAndBroadcast. تعرضها QoreX وتحدد الرسوم وتوقّع بالمفتاحين وتبثّ وتُبلغ عن shield.
  • Solana. تسجّل QoreX محفظة Solana Wallet Standard على solana:mainnet (أي Solana نفسها). مسار SVM الخاص بـ QoreChain غير مفتوح للمعاملات وليس له معرّف سلسلة في Wallet Standard.
  • القدرات، لا الإصدارات. تقرأ الحزم window.qorex.native.capabilities عبر hasCapability. قد يعلن إصدار من QoreX عن listAccounts وconnectProofPicksAccount وexecuteRequest وsignAndBroadcast.
  • يُرفض Amino عمدًا، لأن Amino JSON لا يستطيع حمل توقيع ML-DSA-87 الهجين. تخدم الحزم كل طلب موقّع بموقّع مباشر.
  • signDirect والطبقة ما بعد الكمّية، بدقة. اليوم توقّع signDirect في QoreX الـ SignDoc كما هو بمفتاح secp256k1. وعلى QoreChain يجب أن يحتوي الجسم أصلًا على طبقة ML-DSA-87 هجينة صالحة لمفتاح الموقّع المسجّل، وهو ما لا تستطيع الصفحة إنتاجه. لذلك على qorechain-vladi وqorechain-diana يرمي signDirect في الموقّع غير المتصل التابع للحزم خطأ QOREX_USE_SIGN_AND_BROADCAST قبل أن يصل إلى QoreX؛ بينما تعمل getAccounts على كل سلسلة. وعلى معرّفات سلاسل أخرى تمرّر الحزم signDirect إلى QoreX، التي لا تخدم اليوم إلا معرّفَي سلسلة QoreChain. ومن المخطط أن يضيف إصدار قادم من QoreX الطبقة بنفسه في signDirect وأن يعلن القدرة signDirectAddsPqcLayer؛ ولا يعلنها أي إصدار حالي. الحزم تفحصها أصلًا، وعند إعلانها يمرّر الموقّع غير المتصل SignDocs الخاصة بـ QoreChain إلى QoreX. وقد تعيد QoreX عندها تقدير الغاز وترفع حد الغاز والرسوم، فابثّ دائمًا المستند signed العائد.
  • حالات shield التي تُرجعها signAndBroadcast: ‏shielded (تحمل المعاملة المثبَّتة الطبقة الهجينة)، وpending (تم البثّ ولم يكتمل الفحص)، وdowngraded (ثُبّتت دون الطبقة؛ تعامل معها كتنبيه)، وclassical (مسار لا تنطبق عليه الطبقة).
  • المحاكاة تبني حساباتها من عبارة BIP-39 (الافتراضية: عبارة الاختبار العامة) بالطريقة التي تبنيها بها QoreX: ‏m/44'/118'/0'/0/i مع مفتاح ML-DSA-87 القياسي لعنوان qor1 ذاك، وm/44'/60'/0'/0/i لـ EVM، وm/44'/501'/i'/0' لـ Solana. تقرأ signAndBroadcast فيها مفتاح ML-DSA-87 للحساب من REST، وتسجّله مرة واحدة بـ MsgRegisterPQCKeyV2 إن كان مفقودًا، وتوقّع هجينًا بـ QoreSign، وتبثّ (مع إعادة المحاولة مرة واحدة بالإصدار الآخر من sign-bytes إن طلبت الشبكة ذلك)، وتنتظر الإدراج وتُرجع { txHash, code, height, shield }.

ما تدعمه QoreX اليوم​

السطحاليومالمخطط من فريق QoreX
EVM (‏EIP-1193 عبر EIP-6963، network.qore.qorex)الاتصال (eth_requestAccounts)، وeth_accounts، وeth_chainId، وwallet_switchEthereumChain إلى الشبكة المختارة أصلًا في QoreXأحداث accountsChanged وchainChanged، ورمزا الخطأ 4200 و4902 في EIP-1193 على كل رفض، وpersonal_sign، وeth_signTypedData_v4، وeth_sendTransaction، وwallet_addEthereumChain
المسار الأصلي لـ QoreChain (window.qorex.native)‏enable وgetKey وsignAndBroadcast وlistAccounts وexperimentalSuggestChain (معرّفات QoreChain) وsignDirect (يجب أن يحمل SignDoc الطبقة الهجينة أصلًا)أن تضيف signDirect طبقة ML-DSA-87 بنفسها، وتوقيع الرسائل (ADR-36 زائد ML-DSA-87)
Solana (‏Wallet Standard، solana:mainnet)الاتصال وsignMessage وsignTransactionsolana:signIn

في جانب EVM، يفشل التوقيع والإرسال حاليًا برسالة "QoreX: EVM method ... not yet supported". للمعاملات على QoreChain استخدم المسار الأصلي. وعلى مسار EVM في QoreChain تُقبل المعاملة عندما يكون للمرسل مفتاح ML-DSA-87 مسجّل ونافذة تفويض EVM فُتحت من المسار الأصلي. يغيّر المستخدم الشبكة داخل QoreX؛ ولا يستطيع الـ dApp تبديلها.

كيفية الاستخدام​

كتل الشيفرة أدناه هي البدايات السريعة من مركز المطورين. فُحص كلٌّ منها بـ tsc وشُغّل في 27 أكتوبر 2026 بعد التثبيت من سجل npm العام (Node 26؛ وjsdom 30 وreact-dom/client لشيفرة المتصفح؛ وPlaywright 1.64 مع Chromium للتجهيز) ونجح. لا يرسل أيٌّ منها معاملة ولا يحتاج إلى مفتاح ممول. والنتيجة الملاحَظة مذكورة مع كل منها. لم يُختبر سلوك جانب المحفظة (QoreX حقيقية في متصفح حقيقي) لهذه الصفحة.

@qorechain/qorex-types: اكتشاف QoreX​

npm install @qorechain/qorex-types
import { discoverQorexEip1193, getQorexNative, hasCapability } from "@qorechain/qorex-types";

// EVM: EIP-6963 discovery by rdns "network.qore.qorex" (QoreX never writes window.ethereum).
const evm = await discoverQorexEip1193({ timeoutMs: 500 });
console.log(evm ? "QoreX EVM provider found" : "QoreX EVM provider not announced");

// QoreChain native lane: window.qorex.native.
const native = getQorexNative();
if (native && hasCapability(native, "signAndBroadcast")) {
  const key = await native.getKey("qorechain-diana");
  console.log("native account:", key.bech32Address);
}

الملاحَظ تحت المحاكاة: QoreX EVM provider not announced، ثم native account: qor19rl4cm2hmr8afy4kldpxz3fka4jguq0agt672h. السطر الأول متوقع تحت المحاكاة، انظر تنبيه EIP-6963. لا تعتمد الحزمة على أي تبعيات وقت التشغيل، وتصدّر أيضًا أيقونة QoreX كـ data URI من @qorechain/qorex-types/icon. صادرات أخرى: أنواع المزوّد، وisQorexInstalled، وqorexSignAndBroadcast، ودوال لتصنيف رفض QoreX في EVM.

@qorechain/qorex-rainbowkit: QoreX في RainbowKit وwagmi​

npm install @qorechain/qorex-rainbowkit @rainbow-me/rainbowkit wagmi viem @tanstack/react-query
import { connectorsForWallets } from "@rainbow-me/rainbowkit";
import { metaMaskWallet } from "@rainbow-me/rainbowkit/wallets";
import { createConfig, http } from "wagmi";
import { QOREX_CHAINS, qorechain, qorechainTestnet, qorexWallet } from "@qorechain/qorex-rainbowkit";

const connectors = connectorsForWallets(
  [{ groupName: "Recommended", wallets: [qorexWallet, metaMaskWallet] }],
  { appName: "My dApp", projectId: "<walletconnect project id>" },
);

export const config = createConfig({
  chains: QOREX_CHAINS, // QoreChain mainnet (9801) and testnet (9800)
  connectors,
  transports: { [qorechain.id]: http(), [qorechainTestnet.id]: http() },
});
console.log(config.chains.map((c) => `${c.id} ${c.name}`), connectors.length, "connectors");

الملاحَظ: [ '9801 QoreChain', '9800 QoreChain Testnet' ] 2 connectors. تحوي QOREX_CHAINS تعريفات سلاسل viem لمسار EVM (RPC ‏https://evm.qore.host وhttps://evm-testnet.qore.host، والعملة الأصلية QOR بـ 18 خانة عشرية، والمستكشف https://explore.qore.network). أما projectId فهو معرّف مشروع WalletConnect تنشئه بنفسك لدى WalletConnect. التبعيات النظيرة: viem ^2 وwagmi ^2.9 و@rainbow-me/rainbowkit ^2.2.11. لالتقاط تغييرات الحساب والشبكة التي تُجرى في المحفظة، استخدم wallets: [() => qorexWallet({ pollAccountsOnFocus: true })].

@qorechain/qorex-interchain-kit: تطبيقات Cosmos (موصى بها للأعمال الجديدة)​

npm install @qorechain/qorex-interchain-kit @interchain-kit/core @interchain-kit/react
import type { ComponentProps, ReactNode } from "react";
import { ChainProvider } from "@interchain-kit/react";
import { qorexWallet } from "@qorechain/qorex-interchain-kit";

type Props = Pick<ComponentProps<typeof ChainProvider>, "chains" | "assetLists"> & { children: ReactNode };

// chains / assetLists: your chain-registry entries, including QoreChain.
export function Providers({ chains, assetLists, children }: Props) {
  return (
    <ChainProvider chains={chains} assetLists={assetLists} wallets={[qorexWallet]}>
      {children}
    </ChainProvider>
  );
}

الملاحَظ: رُكّب المكوّن في jsdom مع مُدخل سجل سلاسل شبكة QoreChain التجريبية (@interchain-kit/react 0.11.1). التبعية النظيرة: @interchain-kit/core ^0.11. أرسل معاملة QoreChain بالدالة qorexSignAndBroadcast:

import { qorexSignAndBroadcast } from "@qorechain/qorex-interchain-kit";

const { txHash, code, height, shield } = await qorexSignAndBroadcast({
  chainId: "qorechain-diana",
  messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: msgSendBytes }],
  memo: "",
});

تقبل الدعوة من 1 إلى 32 رسالة ومذكرة (memo) حتى 256 بايت، وتطلب QoreX من المستخدم الموافقة عليها. المقتطف مأخوذ من ملف README الخاص بالحزمة ولم يُشغَّل لهذه الصفحة.

@qorechain/qorex-cosmos-kit: تطبيقات Cosmos على cosmos-kit​

npm install @qorechain/qorex-cosmos-kit @cosmos-kit/core @cosmos-kit/react
import type { ComponentProps, ReactNode } from "react";
import { ChainProvider } from "@cosmos-kit/react";
import { wallets as qorexWallets } from "@qorechain/qorex-cosmos-kit";

type Props = Pick<ComponentProps<typeof ChainProvider>, "chains" | "assetLists"> & { children: ReactNode };

// chains / assetLists: your chain-registry entries, including QoreChain.
export function Providers({ chains, assetLists, children }: Props) {
  return (
    <ChainProvider chains={chains} assetLists={assetLists} wallets={[...qorexWallets]} throwErrors={false}>
      {children}
    </ChainProvider>
  );
}

الملاحَظ: رُكّب في jsdom مع مُدخل شبكة QoreChain التجريبية (@cosmos-kit/react 2.24.1). الخيار throwErrors={false} مطلوب لينجح فحص الأنواع للشيفرة: إذ تعرّف @cosmos-kit/react 2.24 الخاصية throwErrors كخاصية مطلوبة، ويغفلها المثال في README الحزمة. التبعية النظيرة: @cosmos-kit/core ^2.18.1. يوصي README الحزمة بـ Interchain Kit للتطبيقات الجديدة. وتصدّر الحزمة qorexSignAndBroadcast أيضًا.

@qorechain/qorex-wallet-mock: بديل اختباري لـ QoreX​

npm install -D @qorechain/qorex-wallet-mock
import { createQorexMock } from "@qorechain/qorex-wallet-mock";

// jsdom / Vitest: install a QoreX test double into window (public test phrase, testnet only).
const mock = createQorexMock({ profile: "current" });
mock.install(window);

const [account] = (await window.qorex!.evm.request({ method: "eth_requestAccounts" })) as string[];
const chainId = await window.qorex!.evm.request({ method: "eth_chainId" });
console.log(account, chainId, mock.addresses());

الملاحَظ: 0x9858EfFD232B4033E47d90003D41EC34EcaEda94 0x2648 { native: qor19rl4cm2hmr8afy4kldpxz3fka4jguq0agt672h, evm: 0x9858..., svm: HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk }. تُشتق الحسابات بالطريقة التي تشتقها بها QoreX (m/44'/118'/0'/0/i مع مفتاح ML-DSA-87 القياسي لعنوان qor1 ذاك، وm/44'/60'/0'/0/i لـ EVM، وm/44'/501'/i'/0' لـ Solana). تشمل الخيارات profile وmnemonic وaccountIndex وchainId (الافتراضي qorechain-diana) وautoApprove وallowMainnet؛ كما تحصل الصفحة على window.__qorexMock مع approveNext() وrejectNext() وrequests وswitchAccount(i). في Playwright، احقن mock.initScript() بـ page.addInitScript (Node 20.16 أو أحدث).

@qorechain/qorex-synpress: تجهيزات Playwright​

npm install -D @qorechain/qorex-synpress @playwright/test
import { qorexMockFixtures } from "@qorechain/qorex-synpress";

// A Playwright test with the QoreX mock injected before navigation (no Synpress needed).
const test = qorexMockFixtures({ profile: "current" });
const { expect } = test;

test("connects", async ({ page, qorex }) => {
  await page.goto("/");
  await page.getByRole("button", { name: "Connect" }).click();
  await expect(page.getByTestId("account")).toHaveText(qorex.addresses.evm);
});

الملاحَظ: 1 passed، مقابل صفحة محلية يستدعي زر Connect فيها eth_requestAccounts (Playwright 1.64 وChromium). لدمج التجهيزات مع Synpress، ثبّت @synthetixio/synpress@4.1.2 ولُفَّها بـ testWithSynpress. يكشف التجهيز qorex الأعضاء addresses وapproveNext() وrejectNext() وrequests() وswitchAccount(i) وdisconnect(). التبعية النظيرة: @playwright/test ‏1.48 أو أحدث. الحالة تعيش في الصفحة، لذلك يبدأ كل تنقل بمحاكاة جديدة.

إرسال معاملة على QoreChain​

الدعوة نفسها موجودة في @qorechain/qorex-interchain-kit و@qorechain/qorex-cosmos-kit و@qorechain/qorex-types:

import { qorexSignAndBroadcast } from "@qorechain/qorex-interchain-kit";

const { txHash, code, height, shield } = await qorexSignAndBroadcast({
  chainId: "qorechain-diana",
  messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: MsgSend.encode(msg).finish() }],
  memo: "",
  gasLimit: 200000,
});
  • value هي الرسالة المرمّزة بـ protobuf: ‏Uint8Array أو number[] أو base64.
  • من 1 إلى 32 رسالة؛ ومذكرة حتى 256 بايت؛ ويُقيَّد gasLimit بين 100,000 و5,000,000 (و400,000 عند حذفه). تحدد QoreX الرسوم وتعرضها قبل التوقيع.
  • يجب أن يطابق chainId الشبكة المختارة في QoreX.
  • الرسائل التي تدير مفتاح ML-DSA-87 للحساب هي من شأن المحفظة وتُرفض، وكذلك داخل MsgExec. وتُرفض أنواع الرسائل التي لا تستطيع QoreX عرضها.
  • دون حزمة أدوات، استدعِ window.qorex.native.signAndBroadcast(request) بعد التحقق من hasCapability(native, "signAndBroadcast"). تُرجع getKey الحقلين pubKey وaddress كـ number[]؛ حوّلهما بـ Uint8Array.from(key.pubKey) (تفعل الحزم ذلك عنك).

المحاكاة في Playwright دون التجهيزات​

import { createQorexMock } from "@qorechain/qorex-wallet-mock";

const mock = createQorexMock({ profile: "current" });
await page.addInitScript({ content: mock.initScript() });
await page.goto("http://localhost:5173");
await page.evaluate(() => window.__qorexMock!.rejectNext());

واجهة API الرئيسية​

الحزمةالاسمما يفعله
typesdiscoverQorexEip1193({ timeoutMs }), findQorexEip1193()اكتشاف غير متزامن عبر EIP-6963 لمزوّد EVM الخاص بـ QoreX، وفحص متزامن له
typesgetQorexNative(), isQorexInstalled(), hasCapability(native, capability)قراءة window.qorex.native، والتحقق من وجود QoreX، واختبار قدرة
typesqorexSignAndBroadcast(request, { native? })تسلّم الرسائل إلى QoreX؛ وترمي QOREX_NOT_INSTALLED دون QoreX وQOREX_NOT_SUPPORTED_YET على QoreX أقدم منها
typesQorexIntegrationError, isQorexIntegrationError(err, code)أخطاء هذه الحزم، برموز ثابتة
typesisQorexUnsupportedMethodError, isQorexUnrecognizedChainError, QOREX_EVM_ERROR_CODESتصنيف رفض QoreX في EVM: تفحص code (4200 و4902)، ثم تعود إلى نص رسالة اليوم
typesQorexEip1193Provider, QorexNativeProvider, QorexSolanaStandardWallet, QorexSvmProvider; @qorechain/qorex-types/iconأنواع ما تحقنه QoreX؛ وأيقونة QoreX كـ data URI
rainbowkitqorexWallet(options?), createQorexConnector, getQorexEip1193Providerمحفظة RainbowKit (الخيار pollAccountsOnFocus)، وموصّل wagmi، والمزوّد الذي يستخدمه
rainbowkitqorechain, qorechainTestnet, QOREX_CHAINSسلسلتا viem ‏9801 و9800
interchain-kitqorexWallet, createQorexWallet(), QorexCosmosWalletمحفظة Interchain Kit
cosmos-kitwallets, qorexExtension, QorexExtensionWallet, QorexClientمحفظة cosmos-kit
الحزمتان معًاqorexSignAndBroadcast, QOREX_CAPABILITY_SIGN_DIRECT_ADDS_PQC_LAYER, ثوابت معرّفات السلاسل، ودوال الأخطاءيُعاد تصديرها من qorex-types
wallet-mockcreateQorexMock(options)تُرجع { install(window), initScript(), addresses(), ... }
wallet-mockwindow.__qorexMockapproveNext(), rejectNext(), pendingApprovals, requests, clearRequests(), switchAccount(i), switchNetwork(chainId), disconnect(), addresses()
wallet-mockPUBLIC_TEST_MNEMONICعبارة BIP-39 الاختبارية العامة (لا تموّلها أبدًا)
synpressqorexMockFixtures(options)اختبار Playwright ‏test مع تجهيز qorex تلقائي
synpressqorex.addresses, approveNext(), rejectNext(), waitForApproval(), pendingApprovals(), requests(), clearRequests(), switchAccount(i), switchNetwork(chainId), disconnect(), mockعناصر تحكم التجهيز
synpressqorexExtensionFixtures({ extensionPath })واجهة مخطط لها للإضافة الحقيقية؛ وترمي اليوم QorexExtensionModeUnavailableError

مع Synpress v4 ادمج التجهيزات بـ testWithSynpress(qorexMockFixtures({ profile: "planned" })). ومع autoApprove: false، استدعِ await qorex.waitForApproval() لفحص الحالة المعلّقة، ثم qorex.approveNext(). شغّل المجموعة بالملفين معًا لتغطية QoreX اليوم والإصدار القادم.

سلوك موقّع الحزمتين​

الدعوةInterchain Kitcosmos-kit
connect أو enable، getAccount، getKey‏enable وgetKey من QoreX، مع تحويل البايتات إلى Uint8Arrayمثله
getOfflineSigner(chainId)موقّع مباشر لكل تفضيلموقّع مباشر لكل تفضيل، بما فيه الافتراضي "amino" في cosmos-kit
signDirect في الموقّع على QoreChainيرمي QOREX_USE_SIGN_AND_BROADCAST (إلى أن تعلن QoreX signDirectAddsPqcLayer)مثله
signDirect في الموقّع على معرّف سلسلة آخريُمرَّر إلى signDirect في QoreXمثله
signAmino، getOfflineSignerAminoيرمي QOREX_AMINO_REFUSEDمثله
signArbitrary (ADR-36)يرمي QOREX_NOT_SUPPORTED_YET (وكذلك verifyArbitrary)يرمي QOREX_NOT_SUPPORTED_YET
sendTxيرمي QOREX_NOT_SUPPORTED_YET؛ ابثّ عبر نقطة RPC الخاصة بكغير متوفرة

خيارات المحفظة الوهمية​

الخيارالافتراضيالمعنى
profile"current"‏"current" هو QoreX اليوم؛ و"planned" يضيف الميزات المعلن عنها
mnemonicعبارة BIP-39 الاختبارية العامةاستخدم عبارتك الخاصة لأي شيء تموّله
accountIndex0الفهرس نفسه على كل مسار
chainId"qorechain-diana"الشبكة المختارة في المحاكاة
resthttps://api-testnet.qore.hostنقطة REST لـ signAndBroadcast وعمليات البحث عن المفاتيح
evmRpchttps://evm-testnet.qore.hostتستخدمه eth_sendTransaction (الملف planned)
allowMainnetfalseدونه يُرفض التوقيع لـ qorechain-vladi
autoApprovetrueعند false تنتظر الموافقات approveNext() أو rejectNext()
inclusionTimeoutMs, pollIntervalMs30000, 1500كيف تنتظر signAndBroadcast الإدراج

رموز الأخطاء​

من هذه الحزم (QorexIntegrationError.code): ‏QOREX_NOT_INSTALLED وQOREX_USE_SIGN_AND_BROADCAST وQOREX_AMINO_REFUSED وQOREX_NOT_SUPPORTED_YET؛ ومن qorex-synpress: ‏QOREX_EXTENSION_MODE_UNAVAILABLE. أخطاء QoreX نفسها كائنات Error عادية تبدأ رسالتها بـ QoreX، مثل QoreX: connection rejected وQoreX: signature rejected وQoreX: wallet is locked وQoreX: unsupported chain <id>. اليوم تعدّ السلسلة المجهولة (4902) الحالة الوحيدة التي تحمل رمزًا رقميًا، ولا يحمل رفض المستخدم رمز EIP-1193 ‏4001، فطابِق الرسالة. الرسائل التي تبدأ بـ QoreX (mock): تأتي من المحاكاة، وليس من QoreX أبدًا.

كيفية الوصول​

  • محفظة QoreX للاستخدام الحقيقي. تتحدث الموصّلات مع إضافة متصفح QoreX أو تطبيقها الذي ثبّته المستخدم؛ راجع صفحة إضافة متصفح QoreX للتثبيت وإصدارات المتاجر. حزم الاختبار لا تحتاج إلى محفظة.
  • الشبكات. الشبكة الرئيسية qorechain-vladi (معرّف سلسلة EVM ‏9801) والشبكة التجريبية qorechain-diana (معرّف سلسلة EVM ‏9800). تخدم QoreX معرّفي سلسلة QoreChain هذين فقط وترفض غيرهما برسالة "QoreX: unsupported chain". تعتمد المحاكاة الشبكة التجريبية افتراضيًا وترفض التوقيع للشبكة الرئيسية ما لم تمرّر allowMainnet: true.
  • المفاتيح والأموال. الحزم لا تحتفظ بأي مفتاح. تستخدم المحاكاة عبارة BIP-39 الاختبارية العامة (الكلمة abandon مكررة 11 مرة، ثم about) التي تشتق qor19rl4cm2hmr8afy4kldpxz3fka4jguq0agt672h؛ لا تموّلها أبدًا. ولاختبار يبثّ معاملات، أعطِ المحاكاة عبارتك الاستعادية الخاصة بالشبكة التجريبية.
  • حسابات أخرى. يحتاج RainbowKit مع WalletConnect إلى معرّف مشروع WalletConnect من WalletConnect.
  • المتطلبات المسبقة. Node.js (يحتاج سكربت الملف الواحد للمحاكاة إلى 20.16 أو أحدث)، وتطبيق React للموصّلات الثلاثة، والحزم النظيرة المذكورة تحت كل بداية سريعة. يحصل مستخدمو TypeScript على الأنواع من @qorechain/qorex-types.
  • التكاليف. الحزم مجانية. تدفع المعاملة المرسلة عبر QoreX الرسوم المعتادة (الحد الأدنى 0.1 uqor لكل وحدة غاز؛ وتسعّر QoreX معاملاتها الخاصة بـ 0.15 uqor لكل وحدة غاز).

الشبكات​

الشبكة الرئيسيةالشبكة التجريبية
معرّف السلسلة الأصليةqorechain-vladiqorechain-diana
معرّف سلسلة EVM9801 (‏0x2649)9800 (‏0x2648)
RESThttps://api.qore.hosthttps://api-testnet.qore.host
RPChttps://rpc.qore.hosthttps://rpc-testnet.qore.host
EVM JSON-RPChttps://evm.qore.hosthttps://evm-testnet.qore.host
المستكشفhttps://explore.qore.networkنفسه، مع اختيار الشبكة التجريبية

بادئة Bech32 هي qor (والمدققون qorvaloper)، ونوع العملة 118، والعملة uqor بست خانات عشرية على المسار الأصلي وQOR بـ 18 خانة عشرية على EVM. يحتاج المستخدمون إلى إضافة QoreX (0.3.x) للاستخدام الحقيقي؛ أما الاختبارات فتحتاج إلى المحاكاة فقط. وللبثّ الحقيقي من المحاكاة، يحتاج الحساب إلى QOR تجريبي من الصنبور (يتطلب تسجيل الدخول)؛ استخدم عبارتك الخاصة، وليس عبارة الاختبار العامة أبدًا.

ملاحظات أمنية​

  • لا يحمل الـ dApp مفتاح ML-DSA-87 أبدًا: توقّع QoreX معاملات QoreChain داخل المحفظة عبر signAndBroadcast.
  • ترفض QoreX طلبات الصفحة للرسائل التي تدير مفتاح ML-DSA-87 للحساب.
  • لا تعود qorexWallet() أبدًا إلى window.ethereum، فلا يُؤخذ محفظة مُحقونة أخرى على أنها QoreX. وتستخدم المحاكاة اسمًا معكوسًا للنطاق مميزًا كي لا يُؤخذ البديل الاختباري على أنه المحفظة.
  • connectProof وexecuteTransfer وexecuteRequest طرق موجودة للوحة تحكم QoreChain وتُرفض على كل أصل (origin) آخر.
  • راقب نتيجة shield. القيمة downgraded تعني أن المعاملة ثُبّتت دون الطبقة الهجينة؛ تعامل معها كتنبيه.
  • عبارة المحاكاة الافتراضية عامة، وترفض المحاكاة التوقيع للشبكة الرئيسية ما لم تكن allowMainnet: true. لا تموّل عبارة الاختبار العامة أبدًا؛ واستخدم عبارة منفصلة للشبكة التجريبية في الاختبارات الحيّة.
  • أبلغ عن الثغرات سرًّا إلى security@qore.network.

أين تُنشر​

السجلالحزمةالإصدارالرابط
npm@qorechain/qorex-types0.1.0https://www.npmjs.com/package/@qorechain/qorex-types
npm@qorechain/qorex-rainbowkit0.1.0https://www.npmjs.com/package/@qorechain/qorex-rainbowkit
npm@qorechain/qorex-interchain-kit0.1.0https://www.npmjs.com/package/@qorechain/qorex-interchain-kit
npm@qorechain/qorex-cosmos-kit0.1.0https://www.npmjs.com/package/@qorechain/qorex-cosmos-kit
npm@qorechain/qorex-wallet-mock0.1.0https://www.npmjs.com/package/@qorechain/qorex-wallet-mock
npm@qorechain/qorex-synpress0.1.0https://www.npmjs.com/package/@qorechain/qorex-synpress

المصدر: https://github.com/qorechain/qorex-integrations (عام، والإصدار v0.1.0 نُشر في 27 أكتوبر 2026، والمجلدات تحت packages/). ويحوي أيضًا أدلة (إضافة QoreX إلى جانب MetaMask أو Keplr أو Phantom؛ والاختبار الشامل؛ والأخطاء ومعرّفات السلاسل)، وdApp تجريبيًا يختبر كل أسطح QoreX على الشبكة التجريبية، وأمثلة (examples/wagmi-rainbowkit وexamples/playwright-e2e) وملفات مُدخلات سجل السلاسل. الترخيص Apache-2.0؛ والجهة الصائنة جمعية QoreChain. قُرئت الإصدارات من سجل npm في 27 أكتوبر 2026. وهي تحلّ محل @qorechain/connect، الذي صار مهجورًا على npm: استخدم qorex-types لاكتشاف QoreX، وqorex-rainbowkit لتطبيقات EVM، وqorex-interchain-kit (أو qorex-cosmos-kit) لتطبيقات Cosmos، وQoreSign للتوقيع الهجين في محفظتك أو خلفيتك الخاصة.

الحدود والمشكلات المعروفة​

ما تدعمه إصدارات QoreX الحالية. إصدارات المتاجر الحيّة (تطبيق QoreX للجوال 1.1.8؛ وإضافة المتصفح 0.3.8، و0.3.9 على Firefox) لا تدعم بعد getOfflineSigner مع طبقة ML-DSA تضيفها المحفظة، ولا تدعم signArbitrary. عبر cosmos-kit وInterchain Kit، لا يعمل التوقيع بـ getOfflineSigner إلا إذا أرفقت الصفحة نفسها الطبقة ما بعد الكمّية، وهو ما لا تستطيعه الصفحة عادةً لأنها لا تحمل المفتاح. الطريقة المدعومة لإرسال معاملة على المسار الأصلي اليوم هي window.qorex.native.signAndBroadcast، التي تغلّفها qorexSignAndBroadcast. لا تعتبر الموصّلات محفظة كاملة لـ cosmos-kit أو Interchain Kit مع إصدارات المتاجر الحالية، بما يتجاوز ما يذكره README كل حزمة. كُتبت الموصّلات بحيث يستطيع إصدار لاحق من QoreX إضافة الطبقة في signDirect (يُعلَن عنها عبر قدرة signDirectAddsPqcLayer) دون أي تغيير في شيفرتك.

ما تجيب عنه QoreX اليوم (من README الحزم):

  • EVM: ‏eth_chainId وeth_accounts وeth_requestAccounts وwallet_switchEthereumChain للشبكة المختارة في QoreX (تُرفض السلسلة المجهولة بالرمز 4902). طرق التوقيع (personal_sign وeth_signTypedData_v4 وeth_sendTransaction) وwallet_addEthereumChain غير مدعومة بعد وتُرفض برسالة "QoreX: EVM method ... not yet supported". لا أحداث accountsChanged أو chainChanged بعد. أدرجها فريق QoreX كمخطط لها، وليست حيّة: الأحداث، ثم رموز الأخطاء على كل رفض، ثم طرق التوقيع والمعاملات.
  • معاملات EVM عمومًا. على QoreChain لا تُقبل معاملة EVM إلا من حساب لديه مفتاح ML-DSA-87 مسجّل ونافذة تفويض EVM مفتوحة، وكلاهما يُعدّ من المسار الأصلي (راجع تطوير EVM). لا تفتح eth_sendTransaction المخطط لها في المحاكاة تلك النافذة.
  • الأصلي: ‏enable وgetKey وsignDirect وsignAndBroadcast وlistAccounts وexperimentalSuggestChain، لـ qorechain-vladi وqorechain-diana فقط. على QoreChain تحتاج signDirect إلى أن تكون الطبقة الهجينة موجودة مسبقًا، وهو ما لا تستطيع الصفحة بناءه، لذا استخدم signAndBroadcast. أما signArbitrary وتوقيع Amino وsendTx فغير متاحة؛ وفي الموصّلات ترمي signArbitrary الخطأ QOREX_NOT_SUPPORTED_YET ويرمي Amino الخطأ QOREX_AMINO_REFUSED.
  • Solana: ‏Wallet Standard على solana:mainnet مع connect وdisconnect والأحداث وsignAndSendTransaction وsignTransaction وsignMessage؛ بلا solana:signIn. لا يقبل مسار SVM في السلسلة معاملات بعد، فالدعم لـ Solana هنا هو جانب المحفظة فقط.

تنبيهات وُجدت أثناء اختبار البدايات السريعة:

  • يحتاج cosmos-kit إلى throwErrors. يغفل مثال README الخاصية throwErrors التي تطلبها @cosmos-kit/react 2.24 في أنواعها، فلا ينجح فحص الأنواع كما هو مكتوب. مرّر throwErrors={false} (أو قيمتك الخاصة).
  • TypeScript الصارم والمحاكاة. تُرجع window.qorex.evm.request(...) النوع unknown، ولذلك يفشل سطر README الذي يفكّك نتيجتها تحت TypeScript الصارم. حوّل النتيجة بـ cast، مثلًا as string[] لـ eth_requestAccounts.
  • للمحاكاة معرّف EIP-6963 خاص بها. تعلن network.qore.qorex.mock لا network.qore.qorex. لذلك فإن شيفرة الاكتشاف التي تختار QoreX بصرامة بـ network.qore.qorex (ومنها discoverQorexEip1193 في qorex-types) لا تجد مزوّد EVM تحت المحاكاة، عن قصد، بينما يكون window.qorex.evm والمزوّد الأصلي موجودين. إذا كانت شيفرتك تختار المزوّد عبر الاكتشاف، فاجعلها تقبل rdns المحاكاة (المصدَّر باسم QOREX_MOCK_RDNS) في الاختبارات.
  • RainbowKit يُبقي Node حيًّا. في Node، يبدأ بناء إعداد RainbowKit مؤقتات WalletConnect، ولا تنتهي العملية من تلقاء نفسها بعد ذلك. وهذا متوقع في الصفحة. أما في سكربت أو اختبار، فاخرج صراحةً (مثلًا process.exit(0)) بعد أن تقرأ ما تحتاجه.
  • وضع إضافة Synpress لا يعمل بعد. ‏qorexExtensionFixtures هي الطريقة المخطط لها لقيادة الإضافة الحقيقية وترمي اليوم QorexExtensionModeUnavailableError، لأنها تحتاج إلى محددات اختبار مستقرة في نوافذ الموافقة في QoreX لم تصدر بعد. استخدم وضع المحاكاة.

الفروق بين المحاكاة والمحفظة: لا شاشة قفل ولا نافذة موافقة (الموافقات تتم بـ approveNext أو rejectNext أو autoApprove)؛ تُبلغ signDirect عن نوع مفتاح secp256k1 عادي؛ ويُرفض signAndSendTransaction في Solana؛ والرسائل التي تبدأ بـ "QoreX (mock):" هي من المحاكاة نفسها. نتائج الاختبار من المحاكاة تُظهر كيف تتصرف صفحتك مقابل الواجهة الموصوفة، لا أن إصدارًا حقيقيًا من QoreX يتصرف بالطريقة نفسها.

أخرى: الحزم الست جميعها إصدار أولي (0.1.0)، فتوقّع أن تنمو واجهاتها كما تنمو QoreX. لا تغطي أي بداية سريعة مُختبَرة الدالة qorexSignAndBroadcast مقابل شبكة حيّة أو محفظة حقيقية.