كيفية استخدام Solana API: دليل شامل للمطورين

ماذا لو كان بإمكانك بناء تطبيقات بلوكتشين تعالج 65,000 معاملة في الثانية مع إتمام في 400 مللي ثانية؟ واجهة برمجة تطبيقات Solana (API) تجعل هذا ممكنًا، وتقدم واجهة JSON-RPC تتيح لك الاستعلام عن الحسابات، وإرسال المعاملات، والاشتراك في التحديثات في الوقت الفعلي دون الحاجة إلى إدارة البنية التحتية للمدقق بنفسك.

يفرض عليك تطوير البلوكتشين التقليدي الاختيار بين السرعة واللامركزية. معدل 15 معاملة في الثانية لإيثيريوم يخلق اختناقات أثناء ازدحام الشبكة. حلول الطبقة الثانية تضيف تعقيدًا. سولانا تلغي هذه المقايضة من خلال إجماع إثبات التاريخ (proof-of-history) جنبًا إلى جنب مع إثبات الحصة (proof-of-stake)، مقدمة أداء Web2 مع ضمانات Web3. أنت تبني تطبيقات تبدو فورية مع الحفاظ على مقاومة الرقابة.

جدول المحتويات:

• فهم بنية سولانا
• إعداد بيئة التطوير الخاصة بك
• طرق RPC API الأساسية
• بناء المعاملات باستخدام Web3.js
• أفضل ممارسات الأمان
• الخلاصة

فهم بنية سولانا

تستخدم سولانا بنية فريدة تتمحور حول مكتبة برامج سولانا (SPL) وبيئة تشغيل عالية الإنتاجية. يساعدك فهم هذه الأساسيات في كتابة استدعاءات API فعالة.

إثبات التاريخ (PoH)

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

الحسابات والبرامج

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

لكل حساب عنوان فريد بطول 32 بايت مشتق من مفتاح عام Ed25519. تدفع الحسابات إيجارًا باللامبورتات (1 SOL = 10^9 لامبورت) للبقاء على السلسلة. الحسابات المعفاة من الإيجار — تلك التي تحتفظ بإيجار لا يقل عن سنتين — تستمر إلى أجل غير مسمى دون اضمحلال.

مستويات الالتزام

توفر سولانا ثلاثة مستويات للتأكيد:

• معالجة (Processed): معاملة تمت معالجتها بواسطة القائد الحالي ولكن لم يتم تأكيدها. أسرع استجابة، وأقل يقين.
• مؤكدة (Confirmed): معاملة أكدها العنقود. حوالي 5-10 ثوانٍ في المتوسط.
• نهائية (Finalized): معاملة مؤصلة ولا يمكن التراجع عنها. حوالي 12-15 ثانية.

حدد مستويات الالتزام في استدعاءات API للموازنة بين السرعة وضمانات الإتمام النهائي.

إعداد بيئة التطوير الخاصة بك

تحتاج إلى ثلاثة مكونات: واجهة سطر أوامر سولانا (Solana CLI) لإدارة المفاتيح والنشر، ونقطة نهاية RPC للوصول إلى البلوكتشين، وحزمة تطوير البرامج (SDK) لـ JavaScript لتكامل التطبيقات.

تثبيت واجهة سطر أوامر سولانا (Solana CLI)

قم بتثبيت أداة سطر الأوامر الرسمية:

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

تحقق من التثبيت:

solana --version

قم بتكوين بيئتك لشبكة Devnet (للاختبار) أو Mainnet (للإنتاج):

# للتطوير
solana config set --url https://api.devnet.solana.com

# للإنتاج
solana config set --url https://api.mainnet-beta.solana.com

إنشاء محفظة

قم بإنشاء زوج مفاتيح جديد لتوقيع المعاملات:

solana-keygen new --outfile ~/.config/solana/id.json

تعرض واجهة سطر الأوامر عنوانك العام وعبارة أولية تتكون من 12 كلمة. قم بتخزين العبارة الأولية بأمان — فهي تستعيد محفظتك. يحتوي ملف JSON على مفتاحك الخاص؛ قم بحمايته باستخدام أذونات الملفات (chmod 600).

تحقق من رصيدك:

solana balance

قم بتمويل محفظة Devnet الخاصة بك بـ SOL مجاني:

solana airdrop 2

توفر عمليات إسقاط Devnet الجوي 2 SOL لكل طلب، بحد أقصى طلب واحد كل 10 ثوانٍ. تتطلب Mainnet شراء SOL من خلال البورصات.

اختيار موفر RPC

بينما توفر سولانا نقاط نهاية RPC عامة، تحتاج تطبيقات الإنتاج إلى بنية تحتية مخصصة. تتضمن الخيارات:

• Helius: https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
• QuickNode: https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY
• Chainstack: عقد مخصصة بمستوى الشركات

تسمح المستويات المجانية عادة بـ 100,000 طلب شهريًا. توفر الخطط المدفوعة حدودًا أعلى، واتصالات مضمونة لإنهاء المعاملات، وواجهات برمجة تطبيقات لرسوم الأولوية.

تثبيت Web3.js

تحتوي حزمة تطوير البرامج (SDK) لـ JavaScript من سولانا على إصدارين رئيسيين. يمثل الإصدار 2.0 إعادة كتابة كاملة بأنماط برمجة وظيفية، وقابلية لتقليل الحجم (tree-shakability)، وبدون أي تبعيات.

قم بتثبيت الإصدار 2.0:

npm install @solana/web3.js@2 @solana-program/system @solana-program/compute-budget

لتوافق الإصدار 1.x:

npm install @solana/web3.js

نصيحةApidogSolana

طرق Solana RPC API الأساسية

توفر واجهة برمجة تطبيقات Solana JSON-RPC نقاط نهاية HTTP للاستعلامات ونقاط نهاية WebSocket للاشتراكات. تتبع جميع الطلبات مواصفات JSON-RPC 2.0.

عمليات الحساب

احصل على معلومات الحساب والرصيد:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAccountInfo",
    "params": [
      "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
      {"encoding": "base58"}
    ]
  }'

جلب حسابات متعددة بكفاءة:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMultipleAccounts",
    "params": [
      [
        "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
        "4fYNw3dojWGPgVMtUU7ziPwq1r2VMGrhCrKZC9EQTbkV"
      ],
      {"encoding": "base64"}
    ]
  }'

استعلامات الكتل والمعاملات

احصل على أحدث تجزئة للكتلة (blockhash) لإنشاء المعاملات:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLatestBlockhash",
    "params": [{"commitment": "confirmed"}]
  }'

استعلام عن حالة المعاملة:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpEz7CmGVZxhEHppBrGK"
      ],
      {"searchTransactionHistory": true}
    ]
  }'

اشتراكات WebSocket

راقب تغييرات الحساب في الوقت الفعلي:

import { createSolanaRpcSubscriptions } from "@solana/web3.js";

const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);

const abortController = new AbortController();

await rpcSubscriptions.accountNotifications(
  "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
  { commitment: "confirmed" },
  (notification) => {
    console.log("Account changed:", notification);
  },
  { abortSignal: abortController.signal }
);

// توقف عن الاستماع بعد 60 ثانية
setTimeout(() => abortController.abort(), 60000);

تتطلب اتصالات WebSocket إرسال إشارات دورية (pings) كل 30-60 ثانية للبقاء نشطة. قم بتطبيق منطق إعادة الاتصال لتطبيقات الإنتاج.

نصيحة احترافيةApidogSolana

بناء المعاملات باستخدام Web3.js

تتكون معاملات سولانا من تعليمات واحدة أو أكثر تستهدف برامج محددة. تحدد كل تعليمة البرنامج، والحسابات التي تتفاعل معها، والبيانات المتسلسلة.

إنشاء معاملة تحويل

تحويل SOL بين الحسابات باستخدام حزمة تطوير البرامج (SDK) الإصدار 2.0:

import {
  airdropFactory,
  createKeyPairSignerFromBytes,
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  generateKeyPairSigner,
  lamports,
  sendAndConfirmTransactionFactory,
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getSignatureFromTransaction,
} from "@solana/web3.js";
import { getTransferSolInstruction } from "@solana-program/system";

const LAMPORTS_PER_SOL = BigInt(1_000_000_000);

// إعداد اتصالات RPC
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const rpcSubscriptions = createSolanaRpcSubscriptions("wss://api.devnet.solana.com");
const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });

// إنشاء المرسل والمستلم
const sender = await generateKeyPairSigner();
const recipient = await generateKeyPairSigner();

// تمويل المرسل بالإسقاط الجوي
await airdropFactory({ rpc, rpcSubscriptions })({
  recipientAddress: sender.address,
  lamports: lamports(2n * LAMPORTS_PER_SOL),
  commitment: "confirmed",
});

// الحصول على أحدث blockhash
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// بناء المعاملة باستخدام pipe
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (msg) => setTransactionMessageFeePayer(sender.address, msg),
  (msg) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg),
  (msg) => appendTransactionMessageInstruction(
    getTransferSolInstruction({
      amount: lamports(LAMPORTS_PER_SOL / BigInt(2)),
      destination: recipient.address,
      source: sender,
    }),
    msg
  )
);

// توقيع وإرسال
const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
console.log("تم توقيع المعاملة");

await sendAndConfirmTransaction(signedTransaction, {
  commitment: "confirmed",
  maxRetries: 0n,
  skipPreflight: true,
});

console.log("تم التأكيد:", getSignatureFromTransaction(signedTransaction));

تنشئ دالة pipe سلسلة وظيفية حيث تحول كل خطوة رسالة المعاملة. يلغي هذا النمط الحالة القابلة للتغيير ويجعل بناء المعاملة إعلانيًا.

التحسين باستخدام رسوم الأولوية

أثناء ازدحام الشبكة، تضمن رسوم الأولوية إدراج المعاملة. احصل على الرسوم الموصى بها من واجهة برمجة تطبيقات Helius:

import { getBase64EncodedWireTransaction } from "@solana/web3.js";

const base64Transaction = getBase64EncodedWireTransaction(signedTransaction);

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "priority-fee-request",
    method: "getPriorityFeeEstimate",
    params: [{
      transaction: base64Transaction,
      options: { recommended: true }
    }]
  })
});

const { result } = await response.json();
const priorityFee = result.priorityFeeEstimate;

// إضافة تعليمات رسوم الأولوية
import { getSetComputeUnitPriceInstruction } from "@solana-program/compute-budget";

const optimizedMessage = pipe(
  transactionMessage,
  (msg) => appendTransactionMessageInstruction(
    getSetComputeUnitPriceInstruction({ microLamports: priorityFee }),
    msg
  )
);

تُحدد رسوم الأولوية بالمايكرو لامبورت لكل وحدة حساب. تزيد الرسوم الأعلى من أولوية المعاملة أثناء الازدحام.

معالجة الأخطاء

تعيد سولانا رموز خطأ محددة للأعطال الشائعة:

import { isSolanaError, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE } from "@solana/web3.js";

try {
  await sendAndConfirmTransaction(signedTransaction);
} catch (error) {
  if (isSolanaError(error)) {
    switch (error.contextErrorCode) {
      case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE:
        console.error("فشل الفحص المسبق:", error.message);
        break;
      default:
        console.error("خطأ سولانا:", error);
    }
  }
}

تتضمن الأخطاء الشائعة عدم كفاية الأموال (0x1)، وتجزئة الكتلة غير صالحة (منتهية الصلاحية)، والحساب قيد الاستخدام (تعارضات المعاملات).

أفضل ممارسات الأمان

تُدخل إنتاجية سولانا العالية اعتبارات أمان فريدة. قم بتطبيق هذه التدابير لحماية تطبيقك ومستخدميك.

إدارة المفاتيح

لا تقم أبدًا بتضمين المفاتيح الخاصة في التحكم في الإصدار. استخدم متغيرات البيئة:

# .env
SOLANA_PRIVATE_KEY="[1,2,3,...]"

قم بتحميل المفاتيح بأمان في تطبيقك:

import { createKeyPairSignerFromBytes } from "@solana/web3.js";
import { getBase58Encoder } from "@solana/codecs";

const secretKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY);
const signer = await createKeyPairSignerFromBytes(
  new Uint8Array(secretKey)
);

بالنسبة لتطبيقات المتصفح، قم بدمج محولات المحفظة (Phantom, Solflare) بدلاً من التعامل مع المفاتيح الخاصة مباشرةً. يوقع المستخدمون المعاملات من خلال إضافة محفظتهم، مما يحافظ على أمان المفاتيح.

محاكاة المعاملات

قم دائمًا بمحاكاة المعاملات قبل الإرسال لاكتشاف الأخطاء مبكرًا:

const simulationResult = await rpc.simulateTransaction(signedTransaction).send();

if (simulationResult.value.err) {
  console.error("فشلت المحاكاة:", simulationResult.value.err);
  // معالجة الخطأ دون إهدار الرسوم
}

تنفذ المحاكاة المعاملة مقابل الحالة الحالية دون الالتزام بالتغييرات. تكشف عن الأخطاء المنطقية، والحسابات غير الكافية، وانتهاكات ميزانية الحساب.

حماية إعادة التشغيل

تتضمن معاملات سولانا تجزئة كتلة حديثة (blockhash) تنتهي صلاحيتها بعد حوالي 90 ثانية. هذا يمنع هجمات إعادة التشغيل — إرسال نفس المعاملة عدة مرات. للعمليات المتكررة، قم بإنشاء بيانات تعليمات أو حسابات فريدة لكل معاملة.

تحديد المعدل

تطبق نقاط نهاية RPC العامة تحديدًا صارمًا للمعدل (عادةً 100 طلب لكل 10 ثوانٍ). قم بتطبيق تراجع أسي:

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

للإنتاج، استخدم عقد RPC مخصصة أو مستويات موفر مدفوعة بحدود أعلى.

التحقق من البرنامج

قبل التفاعل مع برامج الطرف الثالث، تحقق من الكود المصدري الخاص بها على مستكشفات مثل SolanaFM أو Solscan. ابحث عن شارات التحقق التي تشير إلى أن الكود البايت (bytecode) المنشور يطابق المستودعات مفتوحة المصدر. قد تحتوي البرامج غير الموثقة على منطق ضار يستنزف أموال المستخدمين.

الخلاصة

توفر واجهة برمجة تطبيقات سولانا الأداء الذي تتطلبه التطبيقات الحديثة — إتمام نهائي في أقل من ثانية، وإنتاجية عالية، ورسوم متوقعة. يمكنك الاستعلام عن حالات الحسابات عبر JSON-RPC، والاشتراك في التحديثات في الوقت الفعلي عبر WebSocket، وبناء المعاملات باستخدام حزمة تطوير البرامج (SDK) Web3.js 2.0 الوظيفية. تتيح البنية القائمة على الحسابات التنفيذ المتوازي بينما تتيح لك مستويات الالتزام اختيار الموازنة بين الأمان والسرعة.

ابدأ باستخدام Devnet للتجربة دون مخاطر مالية. استخدم رسوم الأولوية أثناء ازدحام Mainnet. طبق المحاكاة والإدارة الصحيحة للمفاتيح قبل نشر التطبيقات المواجهة للمستخدم. يوفر نظام سولانا البيئي الأدوات؛ منطق تطبيقك يحدد القيمة.

ابدأ مع Apidog اليوم — استورد نقاط نهاية Solana API الخاصة بك في ثوانٍ وابدأ الاختبار بدون أي إعدادات.