دليل البدء السريع لـ Kora

آخر تحديث: 2025-10-31

أساسيات Kora

Kora هو خادم JSON-RPC يوفر خدمات دفع الرسوم لمعاملات سولانا. يتيح للمستخدمين دفع رسوم المعاملات باستخدام رموز SPL بدلاً من SOL، مما يمكّن من تحسين تجربة المستخدم للتطبيقات التي قد لا يمتلك فيها المستخدمون SOL.

يقوم Kora RPC بالتحقق من صحة طلبات العميل بناءً على إعداد (kora.toml) يحدد البرامج والمحافظ والرموز المسموح بها، إلخ. بمجرد التحقق، سيقوم خادم Kora بالتوقيع على المعاملة وإرسالها إلى الشبكة (أو إرجاع معاملة موقعة متسلسلة إلى العميل).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client App    │───▶│   Kora RPC      │───▶│   Solana RPC    │
│                 │    │   Server        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────────┐
                       │   Kora Private Key   │
                       │ ( or Turnkey/Privy ) │
                       └──────────────────────┘

سيقوم هذا البدء السريع بتشغيل خادم Kora RPC محلي وإظهار تكامل العميل لاختبار سير عمل دفع الرسوم.

المتطلبات

• Solana CLI الإصدار 2.2.x أو أحدث
• Rust/Cargo (لتثبيت Kora RPC)
• Node.js الإصدار 22 فما فوق ومدير حزم (مثل pnpm، npm)

تثبيت Kora RPC

قم بتثبيت خادم Kora RPC بشكل شامل:

cargo install kora-cli

مهم: فرع main الخاص بـ Kora هو فرع تكامل وقد يحتوي على تغييرات لم يتم إصدارها أو تجريبية. استخدم دائماً أحدث إصدار مستقر في الإنتاج والاستخدام التعليمي. يمكنك العثور على أحدث إصدار مستقر في صفحة إصدارات Kora.

إنشاء المشروع

استنسخ المستودع، انتقل إلى أحدث علامة مستقرة، وانتقل إلى دليل العرض التوضيحي للبدء:

git clone https://github.com/solana-foundation/kora
cd kora
git checkout v2.0.5
cd examples/getting-started/demo

هيكل المشروع

يحتوي العرض التوضيحي على ثلاثة مكونات رئيسية:

دليل العميل (client/src/)

• setup.ts - إعداد البيئة المحلية (إنشاء keypairs وكتابتها في .env، إسقاط جوي لـ SOL، تهيئة رمز اختبار)
• quick-start.ts - برنامج نصي توضيحي للبدء السريع يوضح إنشاء اتصال Kora وإجراء استدعاء بسيط لخادم Kora RPC
• full-demo.ts - برنامج نصي توضيحي كامل يوضح طرق Kora RPC المتعددة

دليل الخادم (server/)

• kora.toml - إعدادات Kora RPC التي تحدد قواعد التحقق والرموز المسموح بها ومعاملات الرسوم
• signers.toml - إعدادات الموقعين التي تحدد الموقعين لخادم Kora

الإعدادات المشتركة

• .env - متغيرات البيئة لأزواج المفاتيح والعناوين (أنشئ .env في الجذر - demo/.env). سيتم إنشاء متغيرات البيئة بواسطة برنامج الإعداد النصي.

إعداد البيئة

أولاً، أنشئ ملف .env لبيئتك:

# Create .env file (will be populated by setup script)
touch .env

إعداد العميل

ثبّت تبعيات العميل:

# From project root (kora/)
cd examples/getting-started/demo/client
pnpm install --ignore-workspace # use --ignore-workspace to avoid pnpm workspace conflicts

إعداد خادم Kora RPC

يتطلب خادم Kora إعدادات لتحديد الرموز التي يمكن استخدامها لدفع الرسوم. افتح server/kora.toml ولاحظ قسم التحقق. هنا يمكننا تحديد عدة معاملات سيتم التحقق منها قبل التوقيع على معاملة:

• max_allowed_lamports: الحد الأقصى لرسوم المعاملة التي أنت على استعداد لدفعها نيابة عن المستخدم
• max_signatures: الحد الأقصى لعدد التوقيعات التي يمكن أن تحتويها معاملة
• price_source: أوراكل لتحديد سعر الرمز ("Mock" أو "Jupiter")
• allowed_programs: قائمة بيضاء لمعرفات البرامج التي يمكن تنفيذها (مثل System Program، Token Program)
• allowed_tokens: قائمة بيضاء للرموز المسموح بتحويلها
• allowed_spl_paid_tokens: مصفوفة من عناوين السك التي يقبلها برنامجك كدفعة
• disallowed_accounts: قائمة سوداء للحسابات غير المسموح لها بالتفاعل مع Kora RPC الخاص بك

في الوقت الحالي، دعنا نترك القيم الافتراضية--يمكنك العودة هنا وتغييرها لاحقاً (لمزيد من المعلومات حول خيارات الإعدادات، راجع وثائق إعدادات Kora).

إعداد الموقعين

افتح server/signers.toml ولاحظ قسم الموقعين. هنا يمكننا تحديد أي الموقعين سيتم استخدامهم للتوقيع على المعاملات و(في حالة استخدام موقعين متعددين) استراتيجية لاختيار أي موقع سيتم استخدامه. في الوقت الحالي، دعنا نستخدم موقعاً واحداً باستخدام القيم الافتراضية--يمكنك العودة هنا وتغييرها لاحقاً (لمزيد من المعلومات حول إعدادات الموقعين، راجع وثائق دليل الموقعين).

خادم الاختبار

افتح ثلاث نوافذ طرفية وقم بتشغيل الأوامر التالية:

النافذة الطرفية 1: تشغيل مدقق الاختبار المحلي

# From project root or anywhere
solana-test-validator -r

النافذة الطرفية 2: تهيئة البيئة

# From ./client directory
pnpm init-env

سيقوم هذا السكريبت بـ:

• إنشاء أزواج المفاتيح وحفظها في .env
• إرسال SOL إلى حسابات الاختبار
• إنشاء وتهيئة رمز USDC المحلي
• تمويل حسابات الاختبار بالرموز

مهم تأكد من نسخ المفتاح العام لرمز USDC الاختباري الجديد من ملف .env الخاص بك وتحديث allowed_tokens و allowed_spl_paid_tokens في ./server/kora.toml.

allowed_tokens = [
    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env
]
allowed_spl_paid_tokens = [
    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env
]

النافذة الطرفية 3: تهيئة حسابات الرموز المرتبطة للدفع (اختياري)

لاستلام المدفوعات، ستحتاج إلى تهيئة حسابات الرموز المرتبطة (ATAs) لرموز الدفع الخاصة بك. يمكنك القيام بذلك عن طريق تشغيل الأمر التالي:

# From ./server directory
kora rpc initialize-atas --signers-config signers.toml

سيقوم هذا الأمر بـ:

• قراءة عنوان الدفع الخاص بك من kora.toml (أو إذا لم تحدد عنوان دفع، جميع الموقعين المدرجين في signers.toml)
• إنشاء حسابات الرموز المرتبطة لجميع الرموز المدرجة في allowed_spl_paid_tokens
• تخطي أي حسابات رموز مرتبطة موجودة بالفعل
• يمكنك اختياريًا تحديد دافع رسوم مخصص لإنشاء حسابات الرموز المرتبطة باستخدام علامة fee_payer_key.

النافذة الطرفية 4: تشغيل خادم Kora RPC

# From ./server directory
kora rpc start --signers-config signers.toml

ملاحظة: لعمليات النشر الإنتاجية باستخدام price_source = "Jupiter"، يجب عليك تعيين متغير البيئة JUPITER_API_KEY. سيفشل الخادم في التشغيل بدونه:

JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

يقرأ الخادم الإعدادات من kora.toml و signers.toml ويستخدم متغيرات البيئة من ملف .env المشترك. إذا كنت تستخدم هيكل مجلدات مختلف عن المحدد هنا، فقد تحتاج إلى استخدام --config لتحديد موقع kora.toml و --signers-config لتحديد دليل إعدادات الموقعين الخاصة بك:

kora rpc --config path/to/kora.toml start --signers-config path/to/signers.toml

يمكنك الوصول إلى kora rpc -h للحصول على مساعدة حول خيارات خادم RPC.

الطرفية 5: تشغيل عرض العميل التوضيحي

# From ./client directory
pnpm start

يجب أن ترى مخرجات مشابهة لما يلي:

Kora Config: {
  fee_payer: 'Df2UmGQH86TBDsub7XZoSAo7KZa1ZJZr2w1PL1APUjjU',
  validation_config: {
    max_allowed_lamports: 1000000,
    max_signatures: 10,
    allowed_programs: [
      '11111111111111111111111111111111',
      'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
      'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL',
      'AddressLookupTab1e1111111111111111111111111',
      'ComputeBudget11111111111111111111111111111111'
    ],
    allowed_tokens: [
      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'
    ],
    allowed_spl_paid_tokens: [
      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'
    ],
    disallowed_accounts: [],
    price_source: 'Mock',
    fee_payer_policy: {...},
    price: { type: 'margin', margin: 0 }
  },
  enabled_methods: { ... }
 }
}
Blockhash:  C8W8d5w2H4jKXyFg5CEBoiaPvEpJ1am7xLxZ3fym4a2g

هذا يؤكد أن خادم Kora الخاص بك يعمل وتم تكوينه بشكل صحيح!

الخطوات التالية

بمجرد أن يعمل الإعداد الأساسي، راجع العرض التوضيحي الكامل لسير عمل Kora:

← سير عمل المعاملات بدون رسوم الكامل في Kora

استكشف طرق Kora RPC الإضافية:

• estimateTransactionFee - احسب الرسوم للمعاملات
• getPayerSigner - احصل على الموقّع الدافع ووجهة الدفع
• getSupportedTokens - يُرجع مصفوفة من رموز الدفع المدعومة
• signTransaction - وقّع المعاملات بشكل مشروط عندما يتم تغطية الرسوم
• transferTransaction - أنشئ معاملات نقل SOL أو نقل رموز SPL (موقّعة بواسطة دافع رسوم Kora)
• signAndSendTransaction - يوقّع بشكل مشروط على معاملة باستخدام دافع رسوم Kora ويرسلها إلى RPC الخاص بسولانا المُكوّن
• getPaymentInstruction - احصل على تعليمات الدفع لمعاملة ما

لديك أسئلة؟ اطرح الأسئلة على Solana Stack Exchange مع علامة Kora.