دعم امتداد المبلغ المقياسي لواجهة المستخدم على سولانا

الخلفية

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

الموارد:

• وثائق المطورين
• كود Rust للامتداد
• كود Rust لتحويل المبلغ إلى مبلغ واجهة المستخدم

ملخص سريع

• يجب على المستخدمين النهائيين التفاعل مع UIAmount (المبلغ الخام × المضاعف) لسعر الرمز، ورصيد الرمز، ومبالغ الرمز كلما أمكن ذلك
• يجب على تطبيقات dApps ومقدمي الخدمات استخدام المبلغ الخام والأسعار غير المقياسية لجميع الحسابات والتحويل للمستخدمين عند الحافة
• يجب توفير تغذيات الأسعار التاريخية لكل من المبالغ المقياسية وغير المقياسية لتسهيل التكامل
• يجب أن تكون قيم المضاعف التاريخية متاحة للوصول إليها للحصول على بيانات تاريخية دقيقة

تعريفات المصطلحات

• المضاعف: مضاعف ثابت قابل للتحديث يستخدم لحسابات مبلغ واجهة المستخدم
• UIAmount: المضاعف × المبلغ الخام (المعروف أيضًا باسم: المبلغ المقياسي)
• المبلغ الخام: المبلغ (المعروف أيضًا باسم: المبلغ غير المقياسي)

الرصيد الحالي

المبلغ الحالي للعرض

• في أي وقت تعرض فيه مبالغ للرموز التي تستخدم امتداد المبلغ المقياسي لواجهة المستخدم للمستخدمين النهائيين، يجب عليك استخدام إما:
  • UIAmount/UIAmountString (مفضل)
  • حساب يدوي للمبلغ الخام × المضاعف
  • نوصي باقتطاع هذه القيمة بناءً على عدد المنازل العشرية التي يمتلكها الرمز.
    • مثال: إذا كان لـ yUSD 6 منازل عشرية ولدى المستخدم UIAmount بقيمة 1.123456789، فيجب عليك عرض "1.123456"

أين تحصل على هذه البيانات:

• للحصول على الرصيد الحالي للمستخدم يمكنك الحصول على معلومات محدثة عن المبالغ المذكورة أعلاه عن طريق استدعاء إما getTokenAccountBalance أو getAccountInfo
• إذا كنت بحاجة إلى معرفة مبلغ واجهة المستخدم لمبلغ عشوائي، يمكنك الحصول على هذه الحسابات عن طريق استدعاء الدالة amountToUiAmountForMintWithoutSimulation (web3.js v1) أو محاكاة معاملة باستخدام amountToUiAmount.
  • ملاحظة: يتطلب amountToUiAmount محاكاة معاملة مما يعني أنه يحتاج أيضًا إلى دافع رسوم صالح برصيد. لهذا السبب، لا ينبغي أن تكون هذه الطريقة الافتراضية للحصول على الرصيد.

استدعاءات RPC

• getTokenAccountBalance
  • يعيد رصيد حساب الرمز المميز ومعلومات العملة

import { address, createSolanaRpc } from "@solana/kit";
const rpc_url = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(rpc_url);

let tokenAddress = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");

let tokenBalance = await rpc.getTokenAccountBalance(tokenAddress).send();

console.log("Token Balance:", tokenBalance);
/* Token Balance: {
  context: { apiVersion: '2.2.14', slot: 381132711n },
  value: {
    amount: '10000000',
    decimals: 6,
    uiAmount: 20,
    uiAmountString: '20'
  }
} */

• getAccountInfo
  • يعيد معلومات الحساب ومعلومات العملة

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

const rpc_url = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(rpc_url);

const publicKey = address("2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk");
const accountInfo = await rpc.getAccountInfo(publicKey).send();

console.log(
  "Account Info:",
  JSON.stringify(
    accountInfo,
    (key, value) => (typeof value === "bigint" ? value.toString() : value),
    2
  )
);
/* Account Info: {
  "context": {
    "apiVersion": "2.2.14",
    "slot": "381133640"
  },
  "value": {
    "data": {
      "parsed": {
        "info": {
          "extensions": [
            {
              "extension": "immutableOwner"
            },
            {
              "extension": "pausableAccount"
            }
          ],
          "isNative": false,
          "mint": "BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG",
          "owner": "G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib",
          "state": "initialized",
          "tokenAmount": {
            "amount": "10000000",
            "decimals": 6,
            "uiAmount": 20,
            "uiAmountString": "20"
          }
        },
        "type": "account"
      },
      "program": "spl-token-2022",
      "space": "174"
    },
    "executable": false,
    "lamports": "2101920",
    "owner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
    "rentEpoch": "18446744073709551615",
    "space": "174"
  }
} */

تحديث المبلغ الحالي

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

مبالغ الرموز المميزة في المعاملات (التحويلات / المبادلات إلخ)

• يجب على المستخدمين إدخال المبالغ ليتم تفسيرها على أنها "UIAmount" المقياس. يجب على التطبيق الذي يعالج هذا تحويله إلى مبلغ الرمز المميز الخام للمعاملة.
  • إذا كانت هناك مشكلات في التقريب، قم بالتقريب لأسفل ويفضل ترك كمية صغيرة جدًا بدلاً من المخاطرة بفشل المعاملة
  • للقيام بهذا التحويل يمكنك استخدام الدالة uiAmountToAmountForMintWithoutSimulation (web3.js v1) أو محاكاة معاملة باستخدام amountToUiAmount.

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

const connection = new Connection(clusterApiUrl("devnet"), "confirmed");
const mint = new PublicKey("BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG");
const uiAmount = "20.2";

const rawAmount = await uiAmountToAmountForMintWithoutSimulation(
  connection as unknown as Connection,
  mint,
  uiAmount
);
console.log("Raw Amount:", rawAmount);
/* Raw Amount: 20200000 */

• يجب على التطبيقات استخدام المبلغ الإجمالي الخام عندما يطلب المستخدم تنفيذ إجراء بـ "الحد الأقصى" أو "كل" رصيده. هذا يضمن عدم ترك أي غبار متبقي.
  • اختياري: يمكنك التفكير في إغلاق الحساب تلقائيًا عند استخدام "الحد الأقصى" لاسترداد وديعة التخزين للمستخدم

سعر الرمز

• يجب دائمًا عرض سعر الرمز كسعر مقياس حيثما أمكن ذلك.
• إذا كنت مزود خدمة تغذية الأسعار، مثل أوراكل، فيجب عليك عرض كل من السعر المقياس وغير المقياس.
  • حيثما أمكن، قدم SDK/API يجرد تعقيدات امتداد مبلغ واجهة المستخدم المقياس.

المضاعف الحالي

• يمكن قراءة المضاعف الحالي من سك الرمز في أي وقت عن طريق استدعاء getAccountInfo. بالإضافة إلى ذلك، إذا تم تعيين مضاعف مستقبلي، فإن هذه المعلومات متاحة أيضًا من سك الرمز. نوصي بعدم إظهار هذا المضاعف لأنه قد يسبب ارتباكًا في تجربة المستخدم.

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

const rpc_url = "https://api.devnet.solana.com";
const rpc = createSolanaRpc(rpc_url);

const publicKey = address("BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG");
const accountInfo = await rpc
  .getAccountInfo(publicKey, { encoding: "jsonParsed" })
  .send();

const mintData = accountInfo.value?.data as Readonly<{
  parsed: {
    info?: {
      extensions: {
        extension: string;
        state: object;
      }[];
    };
    type: string;
  };
  program: string;
  space: bigint;
}>;

const scaledUiAmountConfig = mintData.parsed.info?.extensions?.find(
  (extension) => extension.extension === "scaledUiAmountConfig"
) as Readonly<{
  state: {
    newMultiplierEffectiveTimestamp: number;
    newMultiplier: number;
    multiplier: number;
  };
}>;

const currentMultiplier =
  scaledUiAmountConfig?.state &&
  Date.now() / 1000 >=
    scaledUiAmountConfig.state.newMultiplierEffectiveTimestamp
    ? scaledUiAmountConfig.state.newMultiplier
    : scaledUiAmountConfig.state.multiplier;

console.log("Scaled UI Amount Config:", scaledUiAmountConfig);
console.log("Current Multiplier:", currentMultiplier);
/*
Scaled UI Amount Config: {
  extension: 'scaledUiAmountConfig',
  state: {
    authority: 'G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib',
    multiplier: '2',
    newMultiplier: '2',
    newMultiplierEffectiveTimestamp: 1743000000n
  }
}
Current Multiplier: 2
*/

البيانات التاريخية

البيانات التاريخية لتغذية الأسعار

• يجب على الخدمات التي توفر بيانات تاريخية تخزين وإظهار كل من الأسعار المقياسة وغير المقياسة لامتداد مبلغ واجهة المستخدم المقياس.
• نتوقع استخدام المبالغ المقياسة بشكل أكثر تكرارًا حيث يتماشى ذلك مع كيفية تعامل عالم التمويل التقليدي مع الرسوم البيانية المتعلقة بالرموز ذات تقسيمات الأسهم.

البيانات التاريخية للمبالغ

• إذا كنت ترغب في إظهار الرصيد المحول في الماضي، فأنت بحاجة إلى الوصول إلى المضاعف في ذلك الـ slot المحدد. يمكنك أيضًا حفظ UiAmount للتحويلات أثناء معالجة المعاملات لتجنب إجراء هذا الحساب في المستقبل.

التوافق مع الإصدارات السابقة

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

أولويات التكامل الموصى بها لكل منصة

المتطلبات العامة

المحافظ

المستكشفون

مجمعو بيانات السوق (مثل: CoinGecko)

مزودو تغذية الأسعار

منصات التبادل اللامركزية