تكامل بروتوكول x402 لسولانا مع Kora RPC

ما الذي ستبنيه

يرشدك هذا الدليل خطوة بخطوة لتنفيذ تكامل كامل لبروتوكول x402 (HTTP 402 Payment Required) مع Kora، البنية التحتية للتوقيع بدون رسوم غاز في سولانا. بنهاية الدليل، سيكون لديك نظام يعمل بشكل كامل حيث:

يمكن لواجهات برمجة التطبيقات (APIs) تحصيل مدفوعات صغيرة مقابل الوصول باستخدام بروتوكول x402
يدفع المستخدمون بـ USDC دون الحاجة إلى SOL لرسوم الغاز
يتولى Kora جميع رسوم المعاملات بوصفه الميسِّر بدون رسوم غاز
تتم تسوية المدفوعات بشكل ذري على بلوكتشين سولانا

ستكون النتيجة النهائية واجهة برمجية محمية بالدفع وتعمل بشكل كامل:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
X402 + KORA PAYMENT FLOW DEMONSTRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/4] Initializing payment signer
  → Network: solana-devnet
  → Payer address: BYJV...TbBc
  ✓ Signer initialized

[2/4] Attempting to access protected endpoint without payment
  → GET http://localhost:4021/protected
  → Response: 402 Payment Required
  ✅ Status code: 402

[3/4] Accessing protected endpoint with x402 payment
  → Using x402 fetch wrapper
  → Payment will be processed via Kora facilitator
  → Transaction submitted to Solana
  ✅ Status code: 200

[4/4] Processing response data
  ✓ Payment response decoded

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUCCESS: Payment completed and API accessed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Response Data:
{
    "data": {
        "message": "Protected endpoint accessed successfully",
        "timestamp": "2025-09-25T20:14:04.242Z"
    },
    "status_code": 200,
    "payment_response": {
        "transaction": "5ULZpdeThaMAy6hcEGfAoMFqJqPpCtxdCxb6JYUV6nA4x8Lk2hKEuzofGUPoe1pop6BdWMSmF5oRPrXsbdWmpruf",
        "success": true,
        "network": "solana-devnet"
    }
}

x402 هو معيار دفع مفتوح يتيح مدفوعات صغيرة سلسة للوصول إلى واجهات برمجة التطبيقات. بدلاً من نماذج الاشتراك التقليدية أو مفاتيح API، يتيح x402 للخوادم تحصيل رسوم مقابل كل طلب API على حدة، مما يُنشئ بنية تحتية حقيقية للدفع مقابل الاستخدام.

المزايا الرئيسية لـ x402:

مدفوعات صغيرة فورية: ادفع أجزاءً من سنت مقابل كل طلب API
تمكين وكلاء الذكاء الاصطناعي من الدفع مقابل طلبات API: الدفع مقابل استدعاءات API باستخدام وكلاء الذكاء الاصطناعي
بلا اشتراكات: يدفع المستخدمون فقط مقابل ما يستخدمونه
مدفوعات Web3: مدفوعات شفافة وقابلة للتحقق على السلسلة
HTTP قياسي: يعمل مع البنية التحتية للويب الحالية باستخدام رمز الحالة HTTP 402 عند الحاجة إلى الدفع

ستُرجع الخوادم التي تستخدم x402 لاشتراط مدفوعات صغيرة للوصول إلى API رمز الحالة HTTP 402 عند الحاجة إلى الدفع. للوصول إلى نقاط النهاية المحمية، يجب على العملاء تمرير دفعة صالحة إلى الخادم في ترويسة X-PAYMENT. يعتمد x402 على "الميسِّرين" للتحقق من المعاملات وتسويتها حتى لا تحتاج الخوادم إلى التفاعل المباشر مع البنية التحتية للبلوكتشين.

فهم الميسِّرين

الميسِّرون مكوّن حاسم في نظام x402. يعملون كخدمات متخصصة تُجرِّد مدفوعات البلوكتشين نيابةً عن خوادم API.

ما يفعله الميسِّرون:

التحقق من المدفوعات: التحقق من صحة حمولات دفع العملاء وكفايتها وتشكيلها بشكل صحيح
تجريد التعقيد: إزالة الحاجة للخوادم للتفاعل المباشر مع البنية التحتية للبلوكتشين (التوقيع ودفع رسوم الشبكة)
تسوية المعاملات: إرسال المعاملات المُتحقق منها إلى سولانا (أو شبكات أخرى)

في العرض التوضيحي، نُنشئ ميسِّراً يستفيد من Kora للتحقق من المعاملات وتسويتها (مزيد من التفاصيل أدناه).

ما هو Kora؟

Kora هو عقدة توقيع سولانا توفر خدمات التوقيع والمعاملات بدون رسوم غاز. يُمكِّن التطبيقات من تجريد رسوم الغاز، مما يسمح للمستخدمين بدفع تكاليف المعاملات بعملات رمزية غير SOL، أو استضافة الرسوم بالكامل.

الميزات الرئيسية لـ Kora:

معاملات بدون رسوم غاز: لا يحتاج المستخدمون إلى SOL لتنفيذ المعاملات
تجريد الرسوم: دفع الرسوم بـ USDC أو غيرها من رموز SPL
واجهة JSON-RPC: واجهة HTTP بسيطة للتعامل مع المعاملات
موقِّعون مرنون: دعم لخلفيات موقِّعين متعددة (الذاكرة، Vault، Turnkey، Privy)
محرك السياسات: تحكم دقيق في التحقق من المعاملات وسياسات الرسوم

في سياق x402، يعمل Kora كخلفية مثالية للميسِّرين: يتولى رسوم الشبكة، ويوقِّع المعاملات، ويتحقق منها.

نظرة عامة على البنية

يتكوّن تكامل x402 + Kora من أربعة مكونات مترابطة مع دورة كاملة للطلب والاستجابة:

دورة الدفع الكاملة:

يطلب العميل المورد المحمي ← تُرجع API استجابة 402 Payment Required
يُنشئ العميل معاملة دفع باستخدام غلاف x402 fetch (الذي يُجمِّع معاملة سولانا مع تعليمات الدفع)
يُرسل العميل الدفعة إلى الميسِّر للتحقق
يتحقق الميسِّر عبر Kora، الذي يوقِّع المعاملة ويُرسلها إلى سولانا
تأكيد المعاملة على السلسلة، يُخطر الميسِّر API
تُرجع API المحتوى المحمي مع إيصال الدفع إلى العميل

تفصيل المكونات

خادم Kora RPC (المنفذ 8080)
- خدمة المعاملات الأساسية بدون رسوم غاز
- يتعامل مع توقيع المعاملات بوصفه دافع الرسوم
- يتحقق من المعاملات وفق السياسات المُهيَّأة
خادم وكيل/غلاف الميسِّر (المنفذ 3000)
- يُكيِّف Kora مع بروتوكول x402
- يُنفِّذ نقاط النهاية /verify و/settle و/supported
- يُترجم بين تنسيقات بيانات x402 و Kora
API المحمية (المنفذ 4021)
- خادم API تجريبي مع نقاط نهاية محمية بالدفع
- يستخدم وسيط x402-express لمعالجة المدفوعات
- يُرجع البيانات فقط بعد نجاح الدفع
تطبيق العميل
- يوضح استخدام غلاف x402 fetch
- يوقِّع المعاملات بالمفتاح الخاص للمستخدم

قد يبدو النهج متعدد المكونات معقداً، لكنه يعكس أنظمة الإنتاج الواقعية حيث تُعدّ معالجة المدفوعات وتشغيل API وتطبيقات العميل اهتمامات منفصلة.

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

Rust (أحدث إصدار مستقر)
Node.js (LTS أو أحدث)
pnpm (أحدث إصدار)
فهم أساسي لـ معاملات سولانا و رموز SPL

إعداد المشروع

الخطوة 1: استنساخ Kora وبناؤه

# Clone the repository
git clone https://github.com/solana-foundation/kora.git
cd kora

# Checkout the release branch as Kora is currently in a feature freeze for audit
git checkout release/feature-freeze-for-audit

# Build and install Kora
make install

يُثبِّت هذا الأمر الملف الثنائي kora على نظامك، والذي سنستخدمه لتشغيل خادم RPC.

الخطوة 2: الانتقال إلى دليل العرض التوضيحي

cd docs/x402/demo

الخطوة 3: تثبيت التبعيات

تثبيت تبعيات Node.js لجميع مكونات العرض التوضيحي:

# Install dependencies for all components (facilitator, API, and client)
pnpm run install:all

يُثبِّت هذا السكريبت التبعيات لـ:

خدمة غلاف الميسِّر
خادم API المحمية
تطبيق العرض التوضيحي للعميل

الخطوة 4: بناء Kora SDK

قم ببناء Kora SDK لنتمكن من استخدام Kora TypeScript SDK في الميسِّر:

pnpm run build:kora-sdk

الخطوة 5: تهيئة البيئة

يتضمن العرض التوضيحي ملف .env.example مع متغيرات البيئة المطلوبة. أولاً، لنُعِدّ الإعداد الأساسي:

# Copy the example environment file
cp .env.example .env

الآن تحتاج إلى إنشاء أزواج keypair أو تقديمها للعرض التوضيحي. شغِّل الأمر التالي لإنشاء keypairs:

pnpm run setup

سيُنشئ هذا keypairs ويُضيفها إلى ملف .env:

KORA_SIGNER_ADDRESS - عنوان موقِّع Kora
KORA_SIGNER_PRIVATE_KEY - المفتاح الخاص لموقِّع Kora
PAYER_ADDRESS - عنوان الدافع الذي سيدفع للوصول إلى API المحمية
PAYER_PRIVATE_KEY - المفتاح الخاص للدافع

الخطوة 5: تحديث ملفات الإعداد

kora.toml

يُهيِّئ ملف kora/kora.toml خادم Kora RPC. لن تحتاج عادةً إلى إجراء أي تغييرات على هذا الملف، لكن يمكنك التحقق من الإعدادات التالية:

رمز الدفع: تأكد من وجود USDC Devnet mint في القائمة المسموح بها:

allowed_tokens = [
    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", # USDC devnet
]

مصادقة API: يستخدم العرض التوضيحي مفتاح API للوصول إلى Kora. يجب أن يتطابق مع KORA_API_KEY في ملف .env:

[kora.auth]
api_key = "kora_facilitator_api_key_example"

سياسة دافع الرسوم: مُهيَّأة لتقييد توقيع المعاملات غير المرغوب فيها:

[validation.fee_payer_policy]
allow_sol_transfers = false
# all other settings are false

البرامج المسموح بها: تأكد من وجود System Program وToken Program وبرنامج الرمز المرتبط وبرنامج ميزانية الحوسبة في القائمة المسموح بها:

allowed_programs = [
    "11111111111111111111111111111111",             # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # Token Program
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program
    "ComputeBudget111111111111111111111111111111",  # Compute Budget Program
]

signers.toml

يُهيِّئ ملف kora/signers.toml موقِّع Kora. لن تحتاج عادةً إلى إجراء أي تغييرات على هذا الملف، لكن يمكنك التحقق من الإعدادات التالية:

متغير بيئة الموقِّع: تأكد من تعيين متغير بيئة الموقِّع، private_key_env، إلى KORA_SIGNER_PRIVATE_KEY (مطابقاً لاسم متغير البيئة في ملف .env).

[[signers]]
name = "main_signer"
type = "memory"
private_key_env = "KORA_SIGNER_PRIVATE_KEY"
weight = 1

الخطوة 6: تمويل الحسابات

SOL الشبكة التجريبية (Devnet)

سيحتاج عنوان موقِّع Kora إلى SOL لدفع رسوم المعاملات. يمكنك إسقاط SOL على الشبكة التجريبية إلى عنوان موقِّع Kora باستخدام Solana CLI:

# Airdrop SOL
solana airdrop 1 <KORA_SIGNER_ADDRESS> --url devnet

بدلاً من ذلك، يمكنك استخدام Solana Faucet لإسقاط SOL إلى عنوان موقِّع Kora.

USDC الشبكة التجريبية (Devnet)

سيحتاج PAYER_ADDRESS المُعيَّن في ملف .env إلى USDC لدفع رسوم المعاملات.

احصل على USDC للشبكة التجريبية من Circle's Faucet. تأكد من اختيار "Solana Devnet" واستخدام PAYER_ADDRESS الخاص بك لطلب USDC.

تشغيل العرض التوضيحي

ستحتاج إلى أربع نوافذ طرفية لتشغيل جميع المكونات من دليل docs/x402/demo.

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

شغِّل الأمر التالي لبدء تشغيل خادم Kora RPC:

pnpm run start:kora

ينبغي أن ترى سلسلة من السجلات تُشير إلى أن خادم Kora RPC يعمل، بما في ذلك:

INFO kora_lib::rpc_server::server: RPC server started on 0.0.0.0:8080, port 8080

الطرفية 2: تشغيل الميسِّر

شغِّل الأمر التالي لبدء تشغيل الميسِّر:

pnpm run start:facilitator

ينبغي أن ترى:

Server listening at http://localhost:3000

الطرفية 3: تشغيل API المحمية

شغِّل الأمر التالي لبدء تشغيل API المحمية:

pnpm run start:api

ينبغي أن ترى:

Server listening at http://localhost:4021

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

pnpm run demo

فهم التنفيذ

إليك ما يحدث خلال تدفق الدفع الناجح:

طلب العميل ← تُرجع API استجابة 402 مع متطلبات الدفع
إنشاء الدفعة ← يُنشئ العميل معاملة سولانا مع الدفعة
إرسال الدفعة ← يُرسل العميل الطلب إلى الخادم مع الدفعة في ترويسة X-PAYMENT
التحقق ← يتحقق الميسِّر عبر signTransaction الخاصة بـ Kora
التسوية ← يُسوِّي الميسِّر عبر signAndSendTransaction الخاصة بـ Kora (إرسال معاملة الدفع إلى سولانا)
منح الوصول ← يُرجع الميسِّر توقيع المعاملة وتُرجع API المحتوى المحمي مع إيصال الدفع

لنتعمق في كيفية عمل كل مكوّن:

Kora RPC (المنفذ 8080): يتعامل مع توقيع المعاملات بدون رسوم غاز
الميسِّر (المنفذ 3000): يربط بروتوكول x402 بـ Kora
API المحمية (المنفذ 4021): نقطة نهاية API المُحوَّلة إلى نموذج ربحي
العميل: يوضح تدفق الدفع التلقائي

خادم وكيل/غلاف الميسِّر

يعمل الميسِّر على المنفذ 3000. هذا هو الخادم الذي يتعامل مع الاتصال مع سولانا (في حالتنا، عبر Kora). يُستخدم للتحقق من مدفوعات x402 وتسويتها.

الميسِّر (facilitator/src/facilitator.ts) هو الجسر بين بروتوكول x402 وKora RPC. يُنفِّذ ثلاث نقاط نهاية رئيسية:

1. نقطة نهاية `/verify`

تقوم نقطة النهاية هذه بـ:

استقبال حمولة دفع x402 من خادم API المحمية
استخراج معاملة سولانا باستخدام مساعدات x402
استخدام signTransaction الخاصة بـ Kora للتحقق من الصحة دون البث
إرجاع حالة التحقق، isValid

2. نقطة نهاية `/settle`

تقوم نقطة النهاية هذه بـ:

استقبال حمولة دفع x402 بعد التحقق منها بواسطة نقطة النهاية /verify
استخدام signAndSendTransaction الخاصة بـ Kora لتوقيع المعاملة وبثّها
إرجاع توقيع المعاملة كدليل على التسوية

3. نقطة نهاية `/supported`

تُعلن نقطة النهاية هذه فعلياً عن قدرات الميسِّر، بما في ذلك:

إصدار x402 المدعوم
نظام الدفع (المدفوعات الدقيقة)
الشبكة (solana-devnet)
عنوان دافع الرسوم الذي نجلبه من Kora باستخدام طريقة getPayerSigner

API المحمية

يستخدم خادم API (api/src/api.ts) وسيط x402-express لحماية نقاط النهاية:

app.use(
  paymentMiddleware(
    KORA_PAYER_ADDRESS, // Where payments should go
    {
      "GET /protected": {
        price: "$0.0001", // Price in USD
        network: NETWORK // solana-devnet
      }
    },
    {
      url: FACILITATOR_URL // Our facilitator wrapper
    }
  )
);

يقوم الوسيط بـ:

اعتراض الطلبات الواردة إلى نقاط النهاية المحمية (في حالتنا، نقطة النهاية /protected)
إرجاع حالة 402 إذا كانت الدفعة مفقودة
التحقق من المدفوعات ومعالجتها عبر الميسِّر
السماح بالوصول بعد نجاح الدفع

على الرغم من أننا نستخدم Express، تتضمن مكتبة x402 دعمًا للبرمجيات الوسيطة للعديد من الأطر الشائعة. راجع حزم x402 TypeScript لمزيد من المعلومات.

تطبيق العميل

يوضح العميل (client/src/index.ts) آليةَ عمل x402 تلقائيًا من خلال إرسال طلب باستخدام استدعاء fetch قياسي ثم إعادة محاولة الطلب مع غلاف الدفع:

// Create a signer from private key
const payer = await createSigner(NETWORK, PAYER_PRIVATE_KEY);

// Wrap fetch with x402 payment capabilities
const fetchWithPayment = wrapFetchWithPayment(fetch, payer);

// First attempt: Regular fetch (will fail with 402)
const expect402Response = await fetch(PROTECTED_API_URL);
console.log(`Status: ${expect402Response.status}`); // 402

// Second attempt: Fetch with payment wrapper (succeeds)
const response = await fetchWithPayment(PROTECTED_API_URL);
console.log(`Status: ${response.status}`); // 200

غلاف fetch الخاص بـ x402:

يكتشف استجابات 402
ينشئ تلقائيًا معاملة دفع بناءً على متطلبات الدفع الخاصة بالـ API المحمية
يوقّع باستخدام المفتاح الخاص للمستخدم
يرسل الدفع إلى الميسِّر للتحقق منه ومعالجته
يعيد محاولة الطلب مع إثبات الدفع في رأس x-payment-response
يُعيد استجابة ناجحة

الخلاصة

تهانينا! 🔥 لقد نجحت في تنفيذ تدفق دفع x402 كامل مع البنية التحتية بدون رسوم غاز من Kora. يوضح هذا العرض التوضيحي كيف:

بروتوكول x402 يُتيح تحقيق الدخل من الـ API بسلاسة عبر المدفوعات الصغيرة
Kora RPC يعمل كميسِّر لمدفوعات x402 عن طريق التحقق من المعاملات وتسويتها
المستخدمون يمكنهم الدفع مقابل الوصول إلى الـ API دون امتلاك SOL أو إدارة رسوم الغاز

تُشكّل هذه البنية أساسًا قويًا لـ:

أسواق وكلاء الذكاء الاصطناعي
واجهات برمجية بنظام الدفع عند الاستخدام
منصات محتوى بالمدفوعات الصغيرة
تسعير SaaS المستند إلى الاستخدام
أي خدمة تتطلب مدفوعات فورية وقابلة للتحقق

يجمع توليفُ x402 وKora قوةَ سولانا إلى البنية التحتية للويب التقليدية.

واصل البناء

تخصيص التسعير: عدّل الـ API لتحصيل مبالغ مختلفة لنقاط نهاية مختلفة
إضافة رموز متعددة: هيّئ Kora لقبول رموز SPL المتنوعة كوسيلة للدفع
النشر في الإنتاج: انشر على الشبكة الرئيسية مع موقّعين للإنتاج (Vault أو Turnkey أو Privy)
ابنِ واجهتك البرمجية الخاصة: أنشئ خدمة حقيقية تحقق دخلًا عبر مدفوعات x402

اطرح أسئلتك على Solana Stack Exchange باستخدام وسمَي kora وx402
افتح مشكلات في مستودع Kora على GitHub

دليل العرض التوضيحي الكامل لتكامل x402 مع Kora