القراءة من الشبكة

يستكشف هذا القسم كيفية قراءة البيانات من شبكة سولانا عن طريق استرجاع حسابات مختلفة لفهم بنية حساب سولانا.

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

Base Account Type

#[derive(PartialEq, Eq, Clone, Default)]
pub struct Account {
    /// lamports in the account
    pub lamports: u64,
    /// data held in this account
    #[cfg_attr(feature = "serde", serde(with = "serde_bytes"))]
    pub data: Vec<u8>,
    /// the program that owns this account. If executable, the program that loads this account.
    pub owner: Pubkey,
    /// this account's data contains a loaded program (and is now read-only)
    pub executable: bool,
    /// the epoch at which this account will next owe rent
    pub rent_epoch: Epoch,
}

الحسابات

يمكن للحسابات على سولانا تخزين "حالة" أو برامج "قابلة للتنفيذ". كل حساب له "عنوان" (مفتاح عام) يعمل كمعرف فريد يستخدم لتحديد موقع البيانات المقابلة على السلسلة.

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

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

هذا الفصل بين شفرة البرنامج وحالة البرنامج هو ميزة أساسية في نموذج حساب سولانا. لمزيد من التفاصيل، راجع صفحة نموذج حساب سولانا.

استرجاع حساب المحفظة

يوضح هذا المثال كيفية:

إنشاء زوج مفاتيح جديد (زوج المفتاح العام/الخاص).
طلب إسقاط جوي من SOL لتمويل العنوان الجديد.
استرجاع بيانات الحساب للعنوان الممول.

على سولانا، يؤدي تمويل عنوان جديد بـ SOL تلقائيًا إلى إنشاء حساب مملوك من قبل System Program. جميع حسابات "المحفظة" هي ببساطة حسابات مملوكة من System Program تحتفظ بـ SOL ويمكنها توقيع المعاملات.

Fetch Account

import { Keypair, Connection, LAMPORTS_PER_SOL } from "@solana/web3.js";

const keypair = Keypair.generate();
console.log(`Public Key: ${keypair.publicKey}`);

const connection = new Connection("http://localhost:8899", "confirmed");

// Funding an address with SOL automatically creates an account
const signature = await connection.requestAirdrop(
  keypair.publicKey,
  LAMPORTS_PER_SOL
);
await connection.confirmTransaction(signature, "confirmed");

const accountInfo = await connection.getAccountInfo(keypair.publicKey);
console.log(JSON.stringify(accountInfo, null, 2));

Console

Click to execute the code.

Fetch Account

import { Keypair, Connection, LAMPORTS_PER_SOL } from "@solana/web3.js";

const keypair = Keypair.generate();
console.log(`Public Key: ${keypair.publicKey}`);

const connection = new Connection("http://localhost:8899", "confirmed");

// Funding an address with SOL automatically creates an account
const signature = await connection.requestAirdrop(
  keypair.publicKey,
  LAMPORTS_PER_SOL
);
await connection.confirmTransaction(signature, "confirmed");

const accountInfo = await connection.getAccountInfo(keypair.publicKey);
console.log(JSON.stringify(accountInfo, null, 2));

Console

Click to execute the code.

"المحفظة" على سولانا هي حساب مملوك من قبل برنامج النظام، وهو أحد البرامج المدمجة في سولانا. تُستخدم حسابات المحفظة بشكل أساسي لحفظ SOL (يتم تتبعها في حقل lamports) وتوقيع المعاملات.

عندما تقوم بجلب حساب محفظة، تتضمن الاستجابة الحقول الموضحة في مثال المخرجات.

يحتوي حقل data على بيانات الحساب المخزنة كبايتات.

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

يشير حقل executable إلى ما إذا كان حقل data للحساب يحتوي على رمز برنامج قابل للتنفيذ.

بالنسبة للمحفظة والحسابات التي تخزن حالة البرنامج، يكون هذا الحقل false.

يحتوي حقل lamports على رصيد الحساب من SOL، مقومًا بوحدة لامبورت.

اللامبورت هي أصغر وحدة من SOL. 1 SOL = 1,000,000,000 لامبورت.

يوضح حقل owner البرنامج الذي يملك الحساب.

بالنسبة للمحافظ، المالك دائمًا هو System Program، بالعنوان 11111111111111111111111111111111.

حقل rentEpoch هو حقل قديم من آلية مهجورة حيث كانت الحسابات تُفرض عليها "rent" (بوحدة lamport) للحفاظ على بياناتها على الشبكة.

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

يوضح حقل space عدد البايتات في حقل data. هذا ليس حقلًا في نوع Account نفسه، ولكنه مُدرج في الاستجابة.

في هذا المثال، حقل space هو 0 لأن حقل data يحتوي على 0 بايت من البيانات.

عندما تقوم بجلب حساب محفظة، تتضمن الاستجابة الحقول الموضحة في مثال المخرجات.

يحتوي حقل data على بيانات الحساب المخزنة كبايتات.

يشير حقل executable إلى ما إذا كان حقل data للحساب يحتوي على رمز برنامج قابل للتنفيذ.

بالنسبة للمحفظة والحسابات التي تخزن حالة البرنامج، يكون هذا الحقل false.

يحتوي حقل lamports على رصيد الحساب من SOL، مقومًا بوحدة لامبورت.

اللامبورت هي أصغر وحدة من SOL. 1 SOL = 1,000,000,000 لامبورت.

يوضح حقل owner البرنامج الذي يملك الحساب.

بالنسبة للمحافظ، المالك دائمًا هو System Program، بالعنوان 11111111111111111111111111111111.

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

يوضح حقل space عدد البايتات في حقل data. هذا ليس حقلًا في نوع Account نفسه، ولكنه مُدرج في الاستجابة.

في هذا المثال، حقل space هو 0 لأن حقل data يحتوي على 0 بايت من البيانات.

Example Output

{
  "data": {
    "type": "Buffer",
    "data": []
  },
  "executable": false,
  "lamports": 1000000000,
  "owner": "11111111111111111111111111111111",
  "rentEpoch": 0,
  "space": 0
}

جلب Token Program

يقوم هذا المثال بجلب Token Program لتوضيح الفرق بين حسابات المحفظة وحسابات البرنامج.

يخزن حساب البرنامج الشفرة الثنائية المُجمّعة لـ الشفرة المصدرية الخاصة بـ Token Program. يمكنك عرض حساب البرنامج هذا على مستكشف سولانا.

Fetch Program Account

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed"
);
const address = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
const accountInfo = await connection.getAccountInfo(address);

Console

Click to execute the code.

Fetch Program Account

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed"
);
const address = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
const accountInfo = await connection.getAccountInfo(address);

Console

Click to execute the code.

Token Program هو حساب برنامج قابل للتنفيذ على سولانا. مثل حسابات المحفظة، تمتلك البرامج نفس بنية البيانات الأساسية Account، ولكن مع اختلافات رئيسية في حقولها.

تم تعيين الحقل executable إلى true، مما يشير إلى أن حقل data لهذا الحساب يحتوي على شفرة برنامج قابلة للتنفيذ.

بالنسبة لحسابات البرامج، يخزن الحقل data الشفرة القابلة للتنفيذ للبرنامج. على العكس من ذلك، تحتوي حسابات المحفظة على حقل بيانات فارغ.

عندما تقوم بنشر برنامج سولانا، يتم تخزين الشفرة القابلة للتنفيذ للبرنامج في حقل data للحساب.

تحتوي حسابات البرامج القابلة للتنفيذ أيضًا على برنامج معين كـ owner للحساب.

جميع حسابات البرامج مملوكة لبرنامج Loader، وهو فئة من البرامج المدمجة التي تمتلك حسابات برامج قابلة للتنفيذ على سولانا.

بالنسبة لـ Token Program، فإن owner هو برنامج BPFLoader2.

تم تعيين الحقل executable إلى true، مما يشير إلى أن حقل data لهذا الحساب يحتوي على شفرة برنامج قابلة للتنفيذ.

عندما تقوم بنشر برنامج سولانا، يتم تخزين الشفرة القابلة للتنفيذ للبرنامج في حقل data للحساب.

تحتوي حسابات البرامج القابلة للتنفيذ أيضًا على برنامج معين كـ owner للحساب.

بالنسبة لـ Token Program، فإن owner هو برنامج BPFLoader2.

Token Program Account

{
  "data": {
    "type": "Buffer",
    "data": [127, "...truncated, total bytes: 134080...", 0]
  },
  "executable": true,
  "lamports": 4522329612,
  "owner": "BPFLoader2111111111111111111111111111111111",
  "rentEpoch": 18446744073709552000,
  "space": 134080
}

جلب حساب mint account

يقوم هذا المثال بجلب حساب mint account لعملة الدولار الأمريكي (USDC) لإظهار كيفية تخزين البرامج على سولانا للحالة في حسابات منفصلة.

حساب Mint هو حساب مملوك لـ Token Program. يخزن البيانات الوصفية العالمية لرمز معين، بما في ذلك إجمالي العرض، وعدد الكسور العشرية، والحسابات المصرح لها بسك أو تجميد الرموز. عنوان حساب mint account يحدد بشكل فريد رمزًا على شبكة سولانا.

Fetch Program Account

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed"
);

const address = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const accountInfo = await connection.getAccountInfo(address);

Console

Click to execute the code.

Fetch Program Account

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed"
);

const address = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const accountInfo = await connection.getAccountInfo(address);

Console

Click to execute the code.

النقطة الأساسية التي يجب ملاحظتها في هذا المثال هي أن حساب Mint يخزن الحالة، وليس الكود القابل للتنفيذ.

حسابات Mint مملوكة من قبل Token Program، الذي يتضمن تعليمات تحدد كيفية إنشاء وتحديث حسابات Mint.

Mint Account

{
  "data": {
    "type": "Buffer",
    "data": [1, "...truncated, total bytes: 82...", 103]
  },
  "executable": false,
  "lamports": 407438077149,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "rentEpoch": 18446744073709552000,
  "space": 82
}

الحقل executable هو false لأن حقل data الخاص بحساب mint يخزن الحالة، وليس الكود القابل للتنفيذ.

يحدد Token Program نوع البيانات Mint، الذي يتم تخزينه في حقل data الخاص بحساب mint.

Mint Account

{
  "data": {
    "type": "Buffer",
    "data": [1, "...truncated, total bytes: 82...", 103]
  },
  "executable": false,
  "lamports": 407438077149,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "rentEpoch": 18446744073709552000,
  "space": 82
}

يحتوي حقل data على حالة الحساب Mint المشفرة، مثل سلطة الإصدار، والعرض الكلي، وعدد الكسور العشرية.

لقراءة حساب Mint، يجب عليك فك تشفير حقل data إلى نوع البيانات Mint. سيتم تناول ذلك في الخطوة التالية.

Mint Account

{
  "data": {
    "type": "Buffer",
    "data": [1, "...truncated, total bytes: 82...", 103]
  },
  "executable": false,
  "lamports": 407438077149,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "rentEpoch": 18446744073709552000,
  "space": 82
}

Token Program (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA) يملك حساب mint.

هذا يعني أن حقل data الخاص بحساب mint يمكن تعديله فقط بواسطة التعليمات المحددة في Token Program.

Mint Account

{
  "data": {
    "type": "Buffer",
    "data": [1, "...truncated, total bytes: 82...", 103]
  },
  "executable": false,
  "lamports": 407438077149,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "rentEpoch": 18446744073709552000,
  "space": 82
}