الجاهزية للإنتاج

يُعد البناء محليًا والاختبار على devnet طرقًا رائعة للبدء مع مدفوعات سولانا. ومع ذلك، عندما تكون مستعدًا للنشر على Mainnet، يجب أن تكون على دراية بالفروق الدقيقة في mainnet. يتسامح Devnet مع الأخطاء. أما Mainnet فلا يتسامح. يغطي هذا الدليل الاختلافات المهمة لضمان حصول المستخدمين على تجربة سلسة.

البنية التحتية لـ RPC

النقاط النهائية العامة (api.mainnet-beta.solana.com) محدودة المعدل بدون اتفاقية مستوى الخدمة. إنها جيدة للتطوير ولكنها ستفشل في تدفقات الدفع الإنتاجية—مثل محاولة تشغيل معالج دفع من خلال واجهة برمجة تطبيقات مشتركة بدون ضمان وقت التشغيل.

عند اختيار مزود RPC، ابحث عن:

• الموثوقية: اتفاقيات مستوى الخدمة مع ضمانات وقت التشغيل (99.9%+)
• الكمون: القرب الجغرافي من المستخدمين
• الميزات: ميزات هبوط المعاملات، والفهرسة، وواجهات برمجة تطبيقات رسوم الأولوية

للحصول على قائمة كاملة بمزودي RPC، راجع دليل مزودو البنية التحتية لـ RPC.

تكوين RPC الاحتياطي

مثل أي مزود خدمة شبكة، يمكن أن يواجه مزودو RPC فترات توقف أو فترات من الأداء المتدهور. لضمان مرونة تطبيقك، يجب عليك تكوين تطبيقك لاستخدام مزودي RPC متعددين.

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

import { RpcTransport } from "@solana/rpc-spec";
import { RpcResponse } from "@solana/rpc-spec-types";
import { createHttpTransport } from "@solana/rpc-transport-http";

// Create a transport for each RPC server
const transports = [
  createHttpTransport({ url: "https://mainnet-beta.my-server-1.com" }),
  createHttpTransport({ url: "https://mainnet-beta.my-server-2.com" }),
  createHttpTransport({ url: "https://mainnet-beta.my-server-3.com" })
];

// Create a wrapper transport that distributes requests to them
let nextTransport = 0;
async function roundRobinTransport<TResponse>(
  ...args: Parameters<RpcTransport>
): Promise<RpcResponse<TResponse>> {
  const transport = transports[nextTransport];
  nextTransport = (nextTransport + 1) % transports.length;
  return await transport(...args);
}

إذا كنت تفضل عدم بناء أدوات التوجيه الخاصة بك، يمكنك الاستفادة من خدمة طرف ثالث مثل Iron Forge للتعامل مع التوجيه نيابة عنك.

هبوط المعاملة

على شبكة Devnet، تهبط المعاملات بسهولة نسبياً. على الشبكة الرئيسية، أنت تتنافس على مساحة الكتلة. لزيادة فرص تضمين معاملتك في كتلة، يجب عليك التأكد من أنك قمت بتجميع معاملتك بشكل صحيح. هذا يعني:

• تضمين blockhash حديث قبل إرسال المعاملة
• تضمين تعليمات رسوم الأولوية في المعاملة مع رسوم أولوية تنافسية
• تضمين تعليمات حد وحدة الحساب في المعاملة مع حد وحدة حساب بناءً على وحدات الحساب المقدرة المطلوبة للمعاملة

بالإضافة إلى ذلك، يجب عليك النظر في أدوات أخرى مثل حزم Jito لزيادة فرص تضمين معاملتك في كتلة. دعنا نستكشف هذه الأدوات بمزيد من التفصيل.

إعدادات إرسال المعاملة

عند إرسال المعاملات على الشبكة الرئيسية، قم بتكوين هذه المعاملات للحصول على معدلات هبوط مثالية:

إدارة Blockhash:

• الجلب باستخدام التزام confirmed
• تخزين lastValidBlockHeight المُرجع بواسطة getLatestBlockhash—هذا يخبرك متى تنتهي صلاحية معاملتك
• تنتهي صلاحية Blockhashes بعد ~150 كتلة (~60-90 ثانية)

خيارات الإرسال:

• maxRetries: 0 — تعطيل إعادة المحاولات التلقائية لـ RPC. تعامل مع إعادة المحاولات بنفسك حتى تتمكن من تحديث blockhash عند الحاجة.
• skipPreflight: true — تجاوز المحاكاة قبل الإرسال. استخدم هذا عندما تكون قد تحققت بالفعل من المعاملة وتريد أقل زمن انتقال. احتفظ به false أثناء التطوير لاكتشاف الأخطاء مبكراً.

import { createSolanaRpc } from "@solana/kit";

const rpc = createSolanaRpc(process.env.RPC_URL!);

// 1. Get blockhash with confirmed commitment
const { value: latestBlockhash } = await rpc
  .getLatestBlockhash({ commitment: "confirmed" })
  .send();

// 2. Build and sign your transaction with the blockhash
// ... (transaction building code)

// 3. Send with production settings
const signature = await rpc
  .sendTransaction(encodedTransaction, {
    encoding: "base64",
    maxRetries: 0n, // Handle retries yourself
    skipPreflight: true, // Skip simulation for speed (use false during dev)
    preflightCommitment: "confirmed"
  })
  .send();

// 4. Track expiration using lastValidBlockHeight
const { lastValidBlockHeight } = latestBlockhash;
// Stop retrying when current block height exceeds lastValidBlockHeight

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

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

كيفية عمل الرسوم:

Total fee = Base fee (5,000 lamports per signature) + Priority fee
Priority fee = Compute units x Price per unit (micro-lamports per compute unit)

التكاليف الفعلية:

• تحويل USDC بسيط: ~$0.001-0.005 في الظروف العادية
• أثناء الازدحام: ~$0.01-0.05
• ذروة الازدحام: يمكن أن ترتفع أكثر

مثال على التنفيذ:

توفر حزمة @solana-program/compute-budget دالة مساعدة لتحديث أو إلحاق تعليمات سعر وحدة الحوسبة (بالميكرو لامبورت) بسهولة إلى معاملة.

import { updateOrAppendSetComputeUnitPriceInstruction } from "@solana-program/compute-budget";

const tx = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayerSigner(payer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
  (m) => appendTransactionMessageInstructions([myInstructions], m),
  (m) => updateOrAppendSetComputeUnitPriceInstruction(1000n as MicroLamports, m)
);

الحصول على تقديرات الرسوم: يقدم معظم موفري RPC واجهات برمجة تطبيقات لرسوم الأولوية:

• Helius Priority Fee API
• QuickNode Priority Fee Add-on
• Triton Priority Fees API

للاطلاع على آليات الرسوم الكاملة، راجع رسوم المعاملات ودليلنا: كيفية إضافة رسوم الأولوية إلى معاملة.

تحسين وحدات الحوسبة

الحوسبة على سولانا هي فعلياً مقياس لمقدار العمل الذي يقوم به البرنامج. هناك حد لمقدار الحوسبة التي يمكن استخدامها في معاملة واحدة (حالياً 1.4 مليون وحدة حوسبة)، وحد لمقدار الحوسبة التي يمكن استخدامها لكل حساب في كل كتلة (حالياً 100 مليون وحدة حوسبة).

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

تحتوي واجهة برمجة تطبيقات JSON RPC الخاصة بـ سولانا على طريقة simulatetransaction يمكن استخدامها لتقدير وحدات الحوسبة المطلوبة لمعاملة ما، والتي تتضمن تقديراً لوحدات الحوسبة التي سيتم استخدامها. توفر @solana/kit دوال مساعدة تُقدّر حدود موارد المعاملة وتضبطها على الرسالة في خطوة واحدة (باستخدام طريقة simulatetransaction داخلياً). بالنسبة للمعاملات من الإصدار الأول، تُقدّر هذه الدوال المساعدة أيضاً حد حجم بيانات الحسابات المحملة.

import {
  estimateResourceLimitsFactory,
  estimateAndSetResourceLimitsFactory
} from "@solana/kit";

const estimateResourceLimits = estimateResourceLimitsFactory({ rpc });
const estimateAndSetResourceLimits = estimateAndSetResourceLimitsFactory(
  estimateResourceLimits
);
const txWithResourceLimits = await estimateAndSetResourceLimits(tx);

في بيئة الإنتاج، إذا كنت تُكرر نفس نوع المعاملة مرات عدة، فيجب أن تفكر في تخزين تقدير الحوسبة للمعاملة مؤقتاً لتجنب عبء تقدير وحدات الحوسبة في كل مرة.

حزم Jito

حزم Jito هي أداة لإدارة التنفيذ الذري لمعاملات متعددة. يتحقق ذلك من خلال إرسال معاملات متعددة إلى شبكة Jito مع إكرامية (tip). يمكن استخدام الإكراميات لتحفيز شبكة Jito على تضمين معاملاتك في كتلة.

الموارد:

• توثيق Jito
• 🎥 فيديو: حزم Jito
• دليل QuickNode حول حزم Jito

استراتيجيات إعادة المحاولة

قد تفشل المعاملات لأسباب عديدة. على عكس واجهات برمجة تطبيقات الدفع التقليدية التي ترجع النجاح أو الفشل فوراً، تستلزم معاملات البلوكتشين تتبع التأكيد.

المفاهيم الأساسية:

• انتهاء صلاحية الـ Blockhash: المعاملات صالحة لمدة ~150 كتلة (~60-90 ثانية)
• الأمان عند إعادة الإرسال (Idempotency): نفس المعاملة الموقّعة تُنتج دائماً نفس التوقيع — إعادة الإرسال آمنة
• التراجع الأسي (Exponential backoff): تجنب إرهاق الشبكة بإعادة المحاولات المتكررة السريعة

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  sendAndConfirmTransactionFactory,
  isSolanaError,
  SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED
} from "@solana/kit";

const rpc = createSolanaRpc(process.env.RPC_URL!);
const rpcSubscriptions = createSolanaRpcSubscriptions(process.env.RPC_WSS_URL!);

const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
  rpc,
  rpcSubscriptions
});

// Send with automatic confirmation tracking and block height monitoring
try {
  await sendAndConfirmTransaction(signedTransaction, {
    commitment: "confirmed",
    // Optional: abort after 75 seconds
    abortSignal: AbortSignal.timeout(75_000)
  });
} catch (e) {
  if (isSolanaError(e, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED)) {
    // Blockhash expired—rebuild transaction with fresh blockhash and retry
    rebuildAndRetryTransaction(); // implement your own logic for rebuilding and retrying the transaction
  }
  throw e;
}

يتولى sendAndConfirmTransactionFactory من @solana/kit إدارة استطلاع التأكيد وتتبع ارتفاع الكتلة تلقائيًا. يُطلق SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED عند انتهاء صلاحية blockhash الخاص بالمعاملة، مما يشير إلى ضرورة إعادة بناء المعاملة باستخدام blockhash جديد.

موارد إضافية

• دليل: تأكيد المعاملات وانتهاء صلاحيتها
• Helius: كيفية تنفيذ المعاملات على سولانا
• QuickNode: استراتيجيات لتحسين معاملات سولانا

فهم مستويات التأكيد

تقدم سولانا ثلاثة مستويات للتأكيد. بمصطلحات التمويل التقليدي:

متى يُستخدم كل مستوى:

• تحديثات واجهة المستخدم: اعرض processed للحصول على ردود فعل فورية ("تم إرسال الدفعة")
• إضافة رصيد للحساب: انتظر confirmed (آمن لمعظم المعاملات)
• شحن البضائع المادية: انتظر finalized
• السحوبات الكبيرة: انتظر finalized
• الامتثال/التدقيق: سجّل دائمًا حالة finalized

لمزيد من المعلومات حول التحقق من حالة المعاملات، راجع التفاعل مع سولانا.

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

توفر Solana Kit أخطاءً مكتوبة عبر isSolanaError(). استخدم رموز أخطاء محددة bedel المطابقة النصية:

import {
  isSolanaError,
  SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED,
  SOLANA_ERROR__TRANSACTION_ERROR__INSUFFICIENT_FUNDS_FOR_FEE,
  SOLANA_ERROR__TRANSACTION_ERROR__BLOCKHASH_NOT_FOUND,
  SOLANA_ERROR__INSTRUCTION_ERROR__INSUFFICIENT_FUNDS
} from "@solana/kit";

function handlePaymentError(error: unknown): {
  message: string;
  retryable: boolean;
} {
  // Blockhash expired—rebuild and retry
  if (
    isSolanaError(error, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED) ||
    isSolanaError(error, SOLANA_ERROR__TRANSACTION_ERROR__BLOCKHASH_NOT_FOUND)
  ) {
    return { message: "Transaction expired—rebuilding", retryable: true };
  }

  // Insufficient SOL for fees
  if (
    isSolanaError(
      error,
      SOLANA_ERROR__TRANSACTION_ERROR__INSUFFICIENT_FUNDS_FOR_FEE
    )
  ) {
    return { message: "Not enough SOL for fees", retryable: false };
  }

  // Insufficient token balance
  if (
    isSolanaError(error, SOLANA_ERROR__INSTRUCTION_ERROR__INSUFFICIENT_FUNDS)
  ) {
    return { message: "Insufficient balance", retryable: false };
  }

  // Unknown error
  console.error("Payment error:", error);
  return { message: "Payment failed—please retry", retryable: true };
}

رموز الأخطاء الشائعة:

المعاملات بدون رسوم غاز

يتوقع المستخدمون الدفع بالعملات المستقرة، لا الحصول على SOL لتغطية رسوم الشبكة. تحلّ المعاملات بدون رسوم غاز هذه المشكلة—على غرار ما يفعله مستخدمو Venmo الذين لا يفكرون في رسوم ACH. اطّلع على تجريد الرسوم للاطلاع على التنفيذ الكامل.

الأمان

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

• لا تكشف أبداً عن المفاتيح الخاصة في كود الواجهة الأمامية. استخدم التوقيع عبر الخادم الخلفي، أو المحافظ المادية، أو محافظ التوقيع المتعدد، أو خدمات إدارة المفاتيح.
• افصل بين المحافظ الساخنة والباردة. المحفظة الساخنة للعمليات اليومية، والباردة للخزينة.
• احتفظ بنسخ احتياطية لجميع مفاتيح الإنتاج. خزّن نسخاً احتياطية مشفرة في مواقع آمنة متعددة. فقدان المفتاح يعني فقدان الوصول بشكل دائم.
• استخدم مفاتيح مختلفة لشبكتَي devnet وmainnet. لا ينبغي أن تكون مفاتيح devnet هي نفسها مفاتيح mainnet. استخدم التهيئة المستندة إلى البيئة لضمان تحميل المفاتيح الصحيحة لكل شبكة.

بنية التوقيع التحتية

للتوقيع عبر الخادم الخلفي في بيئة الإنتاج، استخدم Keychain—مكتبة توقيع موحدة تُجرّد خلفيات إدارة المفاتيح المتعددة من خلال واجهة واحدة: Memory وVault وPrivy وTurnkey وAWS KMS وFireblocks وGCP KMS وCDP وPara وDfns وCrossmint وOpenfort وUtila. يتيح لك ذلك التطوير محلياً باستخدام مفاتيح في الذاكرة، ثم التبديل إلى خلفيات جاهزة للإنتاج دون تغيير كود التطبيق.

لست متأكداً من الخلفية الأنسب لك؟ اطّلع على اختيار خلفية. يتوفر Keychain لكل من Rust وTypeScript.

أمان RPC

تعامل مع نقاط نهاية RPC كمفاتيح API—لا تكشفها في كود الواجهة الأمامية حيث يمكن استخراجها وإساءة استخدامها. استخدم وكيل خادم خلفي أو متغيرات بيئة لا يتم تضمينها في كود العميل.

• QuickNode: أفضل الممارسات لأمان نقاط النهاية
• Helius: احمِ مفاتيح Solana API الخاصة بك: أفضل الممارسات الأمنية

المراقبة

تتبع هذه المقاييس في بيئة الإنتاج:

قم بإعداد تنبيهات لـ:

• التحويلات فوق الحد الأدنى من الخزينة
• ارتفاع معدل فشل المعاملات
• أنماط المستلمين غير الاعتيادية
• زيادة معدل أخطاء RPC

للمراقبة الفورية للمعاملات على نطاق واسع، راجع دليل الفهرسة الخاص بنا.

التحقق من العناوين

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

التكوين القائم على البيئة: غالبًا ما تستخدم Devnet وMainnet عناوين إصدار رموز مختلفة تمامًا. قم بإعداد تكوين تطبيقك لتحميل العناوين الصحيحة لكل بيئة—لا تقم بترميز عناوين الشبكة الرئيسية ثم تنسى تبديلها أثناء الاختبار، أو الأسوأ من ذلك، شحن عناوين devnet إلى بيئة الإنتاج.

بعض عناوين إصدار العملات المستقرة الشائعة هي:

عناوين البرامج مهمة أيضًا. إرسال التعليمات إلى البرنامج الخطأ سيفشل—أو الأسوأ من ذلك، قد يؤدي إلى فقدان لا رجعة فيه للأموال. عناوين Token Program هي:

تحمي قائمة العناوين المسموح بها من الرموز المزيفة، لكنها لا تحمي من الإرسال إلى النوع الخاطئ من الحسابات. يمكن أن يكون عنوان المستلم محفظةً، أو token account، أو mint، أو برنامجًا، وكلٌّ منها يتطلب معالجةً مختلفة. إن أُرسل SOL الأصلي إلى أي شيء غير محفظة، فإنه يخرج عن سيطرة المُرسِل — يُفقد كليًّا في حالة mint أو برنامج، ويمكن استرداده من قِبل مالك الحساب فحسب في حالة token account — دون أي فشل في المعاملة يُنبِّه المستخدم.

قائمة التحقق قبل الإطلاق

• تم الحصول على SOL في الشبكة الرئيسية للرسوم وrent
• تم تهيئة RPC للإنتاج (وليس نقطة نهاية عامة)
• تم تهيئة نقطة نهاية RPC احتياطية
• تم تطبيق رسوم الأولوية مع تسعير ديناميكي
• تتعامل منطق إعادة المحاولة مع انتهاء صلاحية blockhash
• مستوى التأكيد مناسب لحالة الاستخدام
• معالجة جميع الأخطاء الشائعة بشكل سلس
• تم تهيئة Gasless (إن وُجد)
• تم التحقق من عناوين الرموز في الشبكة الرئيسية (وليست devnet mints)
• التحقق من عنوان المستلم قبل الإرسال (محفظة مقابل token account مقابل mint مقابل برنامج)
• تم الاحتفاظ بنسخ احتياطية آمنة لجميع المفاتيح
• مراجعة إدارة المفاتيح (لا مفاتيح في الواجهة الأمامية)
• مراقبة المعاملات والتنبيه نشطان
• تم اختبار الحمل عند الحجم المتوقع

نشر البرامج

إذا كنت تنشر برنامج سولانا مخصصًا كجزء من بنية الدفع التحتية لديك، فثمة اعتبارات إضافية ينبغي مراعاتها.

قبل النشر

• إصدار Solana CLI: تأكد من استخدام أحدث إصدار من Solana CLI.
• keypair الخاص بالبرنامج: سيكون لبرنامجك عنوان مختلف على الشبكة الرئيسية عن شبكة devnet (إلا إذا كنت تُعيد استخدام نفس keypair). قم بتحديث جميع المراجع في إعدادات تطبيقك. احتفظ بـ keypair الخاص ببرنامجك في مكان آمن (لاحظ أن تشغيل cargo clean قد يؤدي على الأرجح إلى حذف keypair الخاص ببرنامجك).
• تهيئة الحسابات: إذا كان برنامجك يتطلب حسابات مسؤول، أو PDAs، أو حسابات حالة أخرى، فتأكد من إنشائها على الشبكة الرئيسية قبل أن يتفاعل المستخدمون مع تطبيقك. وينطبق الأمر ذاته على أي Associated Token Accounts (ATAs) يحتاجها برنامجك.

عملية النشر

• حسابات Buffer: تُنشر البرامج الكبيرة عبر حسابات buffer. يتولى الأمر الأمر solana program deploy تلقائيًا، ولكن يجب أن تعلم أن النشر ليس عملية ذرية—إذا انقطعت، فقد تحتاج إلى استرداد أو إغلاق حسابات buffer. راجع نشر البرامج.
• صلاحية الترقية: قرر ما إذا كان ينبغي أن يكون برنامجك قابلًا للترقية بعد الإطلاق. لضمان الثبات، أبطل صلاحية الترقية بعد النشر. ولمزيد من المرونة، قم بتأمين مفتاح صلاحية الترقية بشكل مناسب.
• الإيجار: تأكد من أن محفظة النشر لديك تحتوي على ما يكفي من SOL لتغطية الحد الأدنى المعفى من الإيجار لجميع program accounts.
• التحقق: تحقق من برنامجك للتأكد من أن البرنامج التنفيذي الذي تنشره على شبكة سولانا يتطابق مع الكود المصدري في مستودعك.

للاطلاع على الإرشادات الكاملة لنشر البرامج، راجع نشر البرامج.