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

Ιστορικό

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

Πόροι:

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

Συνοπτικά

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

Ορισμοί όρων

• Πολλαπλασιαστής: στατικός ενημερώσιμος πολλαπλασιαστής που χρησιμοποιείται για υπολογισμούς UI Amount
• UIAmount: πολλαπλασιαστής * raw amount (γνωστό και ως: scaled amount)
• Raw Amount: ποσό (γνωστό και ως: non-scaled amount)

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

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

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

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

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

Κλήσεις RPC

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

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

$ 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
}

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

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

Ποσά 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.

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

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

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 με διαχωρισμούς μετοχών.
• Οι ενημερώσεις πολλαπλασιαστή μπορεί να περιλαμβάνουν χρονική σήμανση που βρίσκεται στο παρελθόν. Συνιστούμε τη χρήση της χρονικής σήμανσης του block για ιστορικά δεδομένα.
• Σημειώστε ότι ο ενεργός πολλαπλασιαστής μπορεί να είναι ο "multiplier" ή ο "newMultiplier" ανάλογα με την τρέχουσα χρονική σήμανση και το πότε ο νέος πολλαπλασιαστής έχει οριστεί να είναι ενεργός.

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

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

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

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

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

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

Πορτοφόλια

Explorers

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

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

Αποκεντρωμένα ανταλλακτήρια (DEXes)

Κεντρικά ανταλλακτήρια (CEXes)