Υποστήριξη της επέκτασης Scaled UI Amount στο Solana

Υπόβαθρο

Η επέκταση Scaled UI Amount επιτρέπει στους εκδότες token να καθορίσουν έναν πολλαπλασιαστή που θα χρησιμοποιείται κατά τον υπολογισμό του ποσού UI του υπολοίπου token ενός χρήστη. Αυτό επιτρέπει στους εκδότες να δημιουργούν rebasing tokens και να ενεργοποιούν πράγματα όπως διασπάσεις μετοχών. Αυτή η επέκταση, όπως η επέκταση token με τόκο, παρέχει ένα καθαρά διακοσμητικό ποσό UI, που σημαίνει ότι οι ομάδες πρέπει να κάνουν κάποια επιπλέον εργασία για να παρέχουν μια καλή εμπειρία. Οι υποκείμενοι υπολογισμοί και μεταφορές πραγματοποιούνται όλοι χρησιμοποιώντας τα ακατέργαστα ποσά στο πρόγραμμα.

Πόροι:

• Τεκμηρίωση για προγραμματιστές
• Κώδικας Rust επέκτασης
• Κώδικας Rust μετατροπής ποσού σε ποσό UI

Περίληψη

• Οι τελικοί χρήστες θα πρέπει να αλληλεπιδρούν με το UIAmount (ακατέργαστο ποσό * πολλαπλασιαστής) για την τιμή του token, το υπόλοιπο του token και τα ποσά του token όποτε είναι δυνατόν
• Οι dApps και οι πάροχοι υπηρεσιών θα πρέπει να χρησιμοποιούν το ακατέργαστο ποσό και τις μη κλιμακούμενες τιμές για όλους τους υπολογισμούς και να μετατρέπουν για τους χρήστες στο τελικό στάδιο
• Οι ιστορικές τροφοδοσίες τιμών πρέπει να παρέχονται τόσο για κλιμακούμενα όσο και για μη κλιμακούμενα ποσά για ευκολότερη ενσωμάτωση
• Οι ιστορικές τιμές πολλαπλασιαστή πρέπει να είναι προσβάσιμες για ακριβή ιστορικά δεδομένα

Ορισμοί όρων

• Πολλαπλασιαστής: στατικός ενημερώσιμος πολλαπλασιαστής που χρησιμοποιείται για υπολογισμούς ποσού UI
• UIAmount: πολλαπλασιαστής * ακατέργαστο ποσό (γνωστό και ως: κλιμακούμενο ποσό)
• Ακατέργαστο ποσό: ποσό (γνωστό και ως: μη κλιμακούμενο ποσό)

Τρέχον υπόλοιπο

Τρέχον ποσό για εμφάνιση

• Κάθε φορά που εμφανίζετε ποσά για tokens που χρησιμοποιούν την επέκταση scaled UI amount στους τελικούς χρήστες, θα πρέπει να χρησιμοποιείτε είτε:
  • UIAmount/UIAmountString (προτιμώμενο)
  • Έναν χειροκίνητο υπολογισμό του ακατέργαστου ποσού * πολλαπλασιαστή
  • Συνιστούμε την περικοπή αυτής της τιμής με βάση τον αριθμό των δεκαδικών που έχει το token.
    • Π.χ.: αν το yUSD έχει 6 δεκαδικά και ένας χρήστης έχει UIAmount 1.123456789, θα πρέπει να εμφανίζεται "1.123456"

Πού να βρείτε αυτά τα δεδομένα:

• Για το ζωντανό υπόλοιπο ενός χρήστη μπορείτε να λάβετε ενημερωμένες πληροφορίες για τα παραπάνω ποσά καλώντας είτε το getTokenAccountBalance είτε το getAccountInfo
• Αν χρειάζεστε να γνωρίζετε το UI Amount για ένα αυθαίρετο ποσό μπορείτε να κάνετε αυτόν τον υπολογισμό καλώντας τη συνάρτηση amountToUiAmountForMintWithoutSimulation (web3.js v1) ή προσομοιώνοντας μια συναλλαγή χρησιμοποιώντας το amountToUiAmount.
  • Σημείωση: το amountToUiAmount απαιτεί προσομοίωση συναλλαγής που σημαίνει ότι χρειάζεται επίσης έναν έγκυρο πληρωτή τελών με υπόλοιπο. Εξαιτίας αυτού, αυτός δεν θα πρέπει να είναι ο προεπιλεγμένος τρόπος για να λάβετε ένα υπόλοιπο.

Κλήσεις RPC

• getTokenAccountBalance
  • Επιστρέφει το υπόλοιπο του token account και τις πληροφορίες του mint

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
  • Επιστρέφει τις πληροφορίες του λογαριασμού και τις πληροφορίες του mint

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"
  }
} */

Ενημέρωση του τρέχοντος ποσού

Επειδή οι εκδότες μπορούν να ενημερώσουν τον πολλαπλασιαστή οποιαδήποτε στιγμή, μπορείτε να εξετάσετε την περιοδική ανίχνευση για να διατηρείτε ενημερωμένο το υπόλοιπο του λογαριασμού. Οι εκδότες είναι απίθανο να ενημερώσουν αυτόν τον πολλαπλασιαστή περισσότερο από μία φορά την ημέρα. Αν ένας πολλαπλασιαστής έχει οριστεί για μια μελλοντική ημερομηνία, μπορείτε να κάνετε αυτόματη ανίχνευση κατά τη στιγμή αυτής της ενημέρωσης

Ποσά Token σε συναλλαγές (μεταφορές / ανταλλαγές κλπ)

• Οι χρήστες θα πρέπει να εισάγουν ποσά που θα ερμηνεύονται ως το κλιμακωμένο "UIAmount". Η εφαρμογή που πρέπει να επεξεργαστεί αυτό θα πρέπει να μετατρέψει στο ακατέργαστο ποσό token για τη συναλλαγή.
  • Αν υπάρχουν προβλήματα στρογγυλοποίησης, στρογγυλοποιήστε προς τα κάτω και προτιμήστε να αφήσετε ένα μικρό ποσό υπολείμματος παρά να διακινδυνεύσετε την αποτυχία της συναλλαγής
  • Για να κάνετε αυτή τη μετατροπή μπορείτε να χρησιμοποιήσετε τη συνάρτηση 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 */

• Οι εφαρμογές πρέπει να χρησιμοποιούν το συνολικό ακατέργαστο ποσό όταν ένας χρήστης ζητά να κάνει μια ενέργεια με "max" ή "all" του υπολοίπου του. Αυτό διασφαλίζει ότι δεν θα μείνει υπόλοιπο σκόνης.
  • Προαιρετικά: Μπορείτε να εξετάσετε το αυτόματο κλείσιμο ενός λογαριασμού όταν χρησιμοποιείται το "max" για να επιστραφεί στον χρήστη η κατάθεση αποθήκευσής του

Τιμή token

• Η τιμή του token θα πρέπει πάντα να εμφανίζεται ως η κλιμακωμένη τιμή όπου είναι δυνατόν.
• Εάν είστε πάροχος υπηρεσίας τροφοδοσίας τιμών, όπως ένα oracle, θα πρέπει να εκθέτετε τόσο την κλιμακωμένη όσο και τη μη κλιμακωμένη τιμή.
  • Όπου είναι δυνατόν, παρέχετε ένα SDK/API που αφαιρεί τις πολυπλοκότητες επέκτασης του κλιμακωμένου ποσού UI.

Τρέχων πολλαπλασιαστής

• Ο τρέχων πολλαπλασιαστής μπορεί να διαβαστεί από το mint του token ανά πάσα στιγμή καλώντας getAccountInfo. Επιπλέον, εάν έχει οριστεί ένας μελλοντικός πολλαπλασιαστής, αυτή η πληροφορία είναι επίσης διαθέσιμη από το mint του token. Συνιστούμε να μην εμφανίζετε αυτόν τον πολλαπλασιαστή καθώς μπορεί να προκαλέσει σύγχυση στο UX.

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
*/

Ιστορικά δεδομένα

Ιστορικά δεδομένα για τροφοδοσία τιμών

• Οι υπηρεσίες που παρέχουν ιστορικά δεδομένα θα πρέπει να αποθηκεύουν και να εμφανίζουν τόσο τις κλιμακωμένες όσο και τις μη κλιμακωμένες τιμές για την επέκταση του κλιμακωμένου ποσού UI.
• Αναμένουμε ότι τα κλιμακωμένα ποσά θα χρησιμοποιούνται συχνότερα καθώς αυτό ευθυγραμμίζεται με τον τρόπο που ο παραδοσιακός χρηματοοικονομικός κόσμος αντιμετωπίζει τα γραφήματα που σχετίζονται με tokens με διασπάσεις μετοχών.

Ιστορικά δεδομένα για ποσά

• Εάν θέλετε να εμφανίσετε το υπόλοιπο που μεταφέρθηκε στο παρελθόν, χρειάζεστε πρόσβαση στον πολλαπλασιαστή σε εκείνο το συγκεκριμένο slot. Μπορείτε επίσης να αποθηκεύσετε το UiAmount για μεταφορές καθώς επεξεργάζεστε συναλλαγές για να αποφύγετε αυτόν τον υπολογισμό στο μέλλον.

Συμβατότητα με προηγούμενες εκδόσεις

• Εξ ορισμού, τα πορτοφόλια και οι εφαρμογές που δεν κατανοούν την επέκταση κλιμακωμένου ποσού UI θα εμφανίζουν τη σωστή συνολική τιμή μιας δραστηριότητας πολλαπλασιάζοντας τη μη κλιμακωμένη τιμή * με το ακατέργαστο ποσό.
• Ωστόσο, θα εμφανίζουν τη μη κλιμακωμένη τιμή προκαλώντας σύγχυση στους χρήστες.
• Ελπίζουμε ότι αυτό θα ενθαρρύνει τις ομάδες να ενημερώσουν τις dapps τους ώστε να είναι συμβατές με τα tokens που χρησιμοποιούν την επέκταση κλιμακωμένου ποσού UI και είμαστε πρόθυμοι να παρέχουμε υποστήριξη κατά τη διάρκεια αυτής της διαδικασίας.

Προτεινόμενες προτεραιότητες ενσωμάτωσης ανά πλατφόρμα

Γενικές απαιτήσεις

Πορτοφόλια

Εξερευνητές

Συγκεντρωτές δεδομένων αγοράς (π.χ.: CoinGecko)

Πάροχοι τροφοδοσίας τιμών

DEXes