دعم امتداد المبلغ المُحجّم للواجهة على سولانا

الخلفية

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

الموارد:

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

الملخص

• يجب على المستخدمين النهائيين التفاعل مع مبلغ الواجهة (المبلغ الخام * المُضاعِف) لسعر الرمز ورصيد الرمز ومبالغ الرمز كلما أمكن ذلك
• يجب على التطبيقات اللامركزية ومقدمي الخدمات استخدام المبلغ الخام والأسعار غير المُحجّمة لجميع الحسابات والتحويل للمستخدمين عند الحافة
• يجب توفير موجزات الأسعار التاريخية لكل من المبالغ المُحجّمة وغير المُحجّمة لتسهيل التكامل
• يجب أن تكون قيم المُضاعِف التاريخية قابلة للوصول للحصول على بيانات تاريخية دقيقة

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

• المُضاعِف: مُضاعِف ثابت قابل للتحديث يُستخدم لحسابات مبلغ الواجهة
• مبلغ الواجهة: المُضاعِف * المبلغ الخام (يُعرف أيضاً بـ: المبلغ المُحجّم)
• المبلغ الخام: المبلغ (يُعرف أيضاً بـ: المبلغ غير المُحجّم)

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

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

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

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

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

استدعاءات RPC

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

$ curl http://localhost:8899 -s -X POST -H "Content-Type: application/json" -d '
{"jsonrpc": "2.0", "id": 1, "method": "getTokenAccountBalance", "params": ["2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk"]}' | jq .

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "apiVersion": "2.2.14",
      "slot": 381130751
    },
    "value": {
      "amount": "10000000",
      "decimals": 6,
      "uiAmount": 20.0,
      "uiAmountString": "20"
    }
  },
  "id": 1
}

• getAccountInfo
  • يُرجع معلومات الحساب ومعلومات السك

$ curl http://localhost:8899 -s -X POST -H "Content-Type: application/json" -d '
{"jsonrpc": "2.0", "id": 1, "method": "getAccountInfo", "params": ["2uuvxpnEKw52aTqNerHiQ3WeSqZriCMNVt8LhWfrkbPk", {"encoding": "jsonParsed"}]}' | jq .

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "apiVersion": "2.2.14",
      "slot": 381131001
    },
    "value": {
      "data": {
        "parsed": {
          "info": {
            "extensions": [
              {
                "extension": "immutableOwner"
              },
              {
                "extension": "pausableAccount"
              }
            ],
            "isNative": false,
            "mint": "BZCd6HfTbb5ZYJ8hQsm8282tG4QzLyeqFR6tdgQA9EAG",
            "owner": "G7ARQSUCwNrfvTDUCZvM5xdiRdBJiN3qVw2PryD8Wnib",
            "state": "initialized",
            "tokenAmount": {
              "amount": "10000000",
              "decimals": 6,
              "uiAmount": 20.0,
              "uiAmountString": "20"
            }
          },
          "type": "account"
        },
        "program": "spl-token-2022",
        "space": 174
      },
      "executable": false,
      "lamports": 2101920,
      "owner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
      "rentEpoch": 18446744073709551615,
      "space": 174
    }
  },
  "id": 1
}

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

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

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

• يجب على المستخدمين إدخال المبالغ ليتم تفسيرها على أنها "مبلغ واجهة المستخدم" المُحجّم. يجب على التطبيق الذي يتعين عليه معالجة هذا أن يحوّل إلى مبلغ الرمز الخام للمعاملة.
  • إذا كانت هناك مشاكل في التقريب، قرّب للأسفل وفضّل ترك كمية ضئيلة من الغبار بدلاً من المخاطرة بفشل المعاملة
  • للقيام بهذا التحويل يمكنك استخدام دالة 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، Birdeye)

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

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

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