مجموعة أدوات العميل

@solana/kit يوفر createClient، وهو مضيف صغير يمكن توسيعه بالإضافات. كل إضافة تضيف قدرة معينة — اتصال RPC، أو موقّع، أو تخطيط معاملات — ويدعم العميل المُركَّب البرامج النصية ومسارات الخادم وواجهات المستخدم على حدٍّ سواء.

التثبيت

$ 
npm install @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signerCopy

استخدم أي مدير حزم. Kit بإصدار v7+ وحزم @solana/kit-plugin-* بإصدار 0.13+.

إنشاء عميل

ركّب الإضافات باستخدام .use(...). اضبط الموقّع أولاً، ثم اتصال RPC. يضيف solanaDevnetRpc() كلاً من client.rpc والاشتراكات ومخطط/منفّذ المعاملات ومساعد client.sendTransaction — لذا نادراً ما يحتاج التطبيق إلى توصيل هذه الأجزاء بنفسه.

import { createClient, generateKeyPairSigner } from "@solana/kit";
import { solanaDevnetRpc } from "@solana/kit-plugin-rpc";
import { signer } from "@solana/kit-plugin-signer";

const payer = await generateKeyPairSigner();

const client = createClient().use(signer(payer)).use(solanaDevnetRpc());

const slot = await client.rpc.getSlot().send();
console.log("current slot", slot);

تُعيِّن إضافة signer كلاً من دافع الرسوم وهوية التطبيق. تستلزم حزمة RPC وجود دافع مسبقاً، وهذا هو سبب أهمية الترتيب.

أنواع الموقّعين

تعرض @solana/kit-plugin-signer ثلاثة أدوار لتمنح فقط ما يحتاجه العميل:

• signer(x) — يُعيِّن كلاً من client.payer وclient.identity.
• payer(x) — دافع الرسوم فقط.
• identity(x) — سلطة التطبيق فقط.

لكل منها متغيرات *FromFile(path) (Node) وgenerated*() وgenerated*WithSol(amount) وairdrop*() للاختبارات والبرامج النصية.

إرسال معاملة

ابنِ التعليمات باستخدام عميل برنامج مُولَّد، ثم مرّرها إلى client.sendTransaction. يحلّ المخطط الـ blockhash، ويقدّر الحوسبة، ويوقّع باستخدام دافع العميل، ثم يرسل.

import { getTransferSolInstruction } from "@solana-program/system";
import { address, lamports } from "@solana/kit";

const transfer = getTransferSolInstruction({
  source: client.payer,
  destination: address("Fke...address"),
  amount: lamports(10_000_000n) // 0.01 SOL
});

const { context } = await client.sendTransaction([transfer]);
console.log("submitted", context.signature);

يُحلِّل sendTransaction إلى كائن نتيجة؛ توقيع المعاملة موجود في result.context.signature. يتحقق من أن الخطة تلائم معاملة واحدة ويرمي استثناءً في الحالة المعاكسة — استخدم sendTransactions حين قد تمتد الدُّفعة على عدة معاملات.

اختيار حزمة RPC

تشحن @solana/kit-plugin-rpc إعدادات مسبقة للشبكات:

• solanaDevnetRpc() — إعدادات devnet الافتراضية، الإسقاط الجوي مُفعَّل (client.airdrop).
• solanaMainnetRpc() — الشبكة الرئيسية؛ الإسقاط الجوي خطأ في وقت الترجمة.
• solanaLocalRpc() — http://127.0.0.1:8899 لـ validator محلي.
• solanaRpc({ rpcUrl }) — أي نقطة نهاية.

import { solanaRpc } from "@solana/kit-plugin-rpc";

const client = createClient()
  .use(signer(payer))
  .use(solanaRpc({ rpcUrl: "https://your-rpc-provider.example" }));

التركيب التفصيلي

تجمع الإعدادات المسبقة بين اتصال RPC والمخطط والمنفّذ ومساعدات الإرسال، لذا لا تحتاج معظم التطبيقات إلى الأجزاء الفردية. انتقل إلى الإضافات التفصيلية فقط لتخصيص إحداها — كمخطط مخصص أو قناة اشتراك مختلفة. يحتاج هذا المسار أيضاً إلى @solana/kit-plugin-instruction-plan، الذي تتضمنه الإعدادات المسبقة عادةً:

import {
  solanaRpcConnection,
  rpcAirdrop,
  rpcTransactionPlanner,
  rpcTransactionPlanExecutor
} from "@solana/kit-plugin-rpc";
import { planAndSendTransactions } from "@solana/kit-plugin-instruction-plan";

const client = createClient()
  .use(signer(payer))
  .use(solanaRpcConnection({ rpcUrl: "https://api.devnet.solana.com" }))
  .use(rpcAirdrop())
  .use(rpcTransactionPlanner())
  .use(rpcTransactionPlanExecutor())
  .use(planAndSendTransactions());

إضافة عملاء البرامج

تعرض حزم @solana-program/* المُولَّدة إضافات عميل كي تتدلى استدعاءات البرنامج من العميل. ثبّت البرنامج الذي تحتاجه واستخدم .use() مع إضافته:

import { tokenProgram } from "@solana-program/token";

const client = createClient()
  .use(signer(payer))
  .use(solanaDevnetRpc())
  .use(tokenProgram()); // adds client.token

التوقيع بدون محفظة متصفح

هل تعمل في وضع headless داخل مسار API أو عامل أو برنامج نصي؟ وقّع باستخدام خدمة إدارة مفاتيح خلفية بدلاً من keypair خام. انظر Keychain و التوقيع في الإنتاج.

أنماط شائعة لمطوري سولانا

• إعداد مشترك: ابنِ العميل مرة واحدة في وحدة أساسية واستورده في البرامج النصية ومسارات الخادم وواجهة المستخدم.
• قراءة من جانب الخادم: يقرأ عميل يضم signer + solanaRpc فقط (بدون إضافة محفظة) الحسابات ويحاكي المعاملات من الخادم.
• الاختبار المحلي: استبدل حزمة RPC بـ .use(litesvm()) من @solana/kit-plugin-litesvm للتشغيل مقابل validator في الذاكرة (Node فقط).
• قابلية الاختبار: العميل المُركَّب سهل المحاكاة — استبدل استجابات RPC أو الموقّعين بدون الحاجة إلى محفظة متصفح.