Coin denomination info for SUI (MystenLabs#5181)

.changeset/polite-emus-doubt.md

@@ -0,0 +1,5 @@
+---
+"@mysten/sui.js": patch
+---
+
+Introduce getCoinDenominationInfo, which returns denomination info of a coin, now only supporting SUI coin.

sdk/typescript/src/providers/json-rpc-provider.ts

@@ -24,6 +24,7 @@ import {
   DEFAULT_START_TIME,
   EVENT_QUERY_MAX_LIMIT,
   ExecuteTransactionRequestType,
+  CoinDenominationInfoResponse,
   GatewayTxSeqNumber,
   GetObjectDataResponse,
   getObjectReference,
@@ -49,6 +50,7 @@ import {
   TransactionDigest,
   TransactionQuery,
   SUI_TYPE_ARG,
+  normalizeSuiAddress,
 } from '../types';
 import { SignatureScheme } from '../cryptography/publickey';
 import {
@@ -221,6 +223,23 @@ export class JsonRpcProvider extends Provider {
     return objects.filter((obj: SuiObjectInfo) => Coin.isSUI(obj));
   }
 
+  getCoinDenominationInfo(
+    coinType: string,
+  ): CoinDenominationInfoResponse {
+    const [packageId, module, symbol] = coinType.split('::');
+    if (normalizeSuiAddress(packageId) !== normalizeSuiAddress('0x2') || module != 'sui' || symbol !== 'SUI') {
+      throw new Error(
+        'only SUI coin is supported in getCoinDenominationInfo for now.'
+      );
+    }
+
+    return {
+      coinType: coinType,
+      basicUnit: 'MIST',
+      decimalNumber: 9,
+    };
+  }
+
   async getCoinBalancesOwnedByAddress(
     address: string,
     typeArg?: string

sdk/typescript/src/providers/provider.ts

@@ -3,6 +3,7 @@
 
 import { SignatureScheme } from '../cryptography/publickey';
 import {
+  CoinDenominationInfoResponse,
   GetObjectDataResponse,
   SuiObjectInfo,
   GatewayTxSeqNumber,
@@ -95,6 +96,25 @@ export abstract class Provider {
     exclude: ObjectId[]
   ): Promise<GetObjectDataResponse[]>;
 
+  /**
+   * Method to look up denomination of a specific type of coin.
+   * TODO: now only SUI coins are supported, will scale to other types
+   * based on their definitions in Move.
+   * 
+   * @param coin_type coin type, e.g., '0x2::sui::SUI'
+   * @return denomination info of the coin including,
+   * coin type, the same as input coin type
+   * basic unit, the min unit of the coin, e.g., MIST;
+   * canonical unit, the commonly used unit, e.g., SUI;
+   * denomination, the value of 1 canonical over 1 basic unit,
+   * for example 1_000_000_000 = 1 SUI / 1 MIST;
+   * decimal number, the number of zeros in the denomination,
+   * e.g., 9 here for SUI coin.
+   */
+  abstract getCoinDenominationInfo(
+    coin_type: string,
+  ): CoinDenominationInfoResponse;
+
   /**
    * Get details about an object
    */

sdk/typescript/src/providers/void-provider.ts

@@ -4,6 +4,7 @@
 import { SignatureScheme } from '../cryptography/publickey';
 import {
   CertifiedTransaction,
+  CoinDenominationInfoResponse,
   TransactionDigest,
   GetTxnDigestsResponse,
   GatewayTxSeqNumber,
@@ -48,6 +49,12 @@ export class VoidProvider extends Provider {
     throw this.newError('getGasObjectsOwnedByAddress');
   }
 
+  getCoinDenominationInfo(
+    _coin_type: string,
+  ): CoinDenominationInfoResponse {
+    throw this.newError('getCoinDenominationInfo');
+  }
+
   async getCoinBalancesOwnedByAddress(
     _address: string,
     _typeArg?: string

sdk/typescript/src/types/index.guard.ts

@@ -7,7 +7,7 @@
  * Generated type guards for "index.ts".
  * WARNING: Do not manually change this file.
  */
-import { TransactionDigest, SuiAddress, ObjectOwner, SuiObjectRef, SuiObjectInfo, ObjectContentFields, MovePackageContent, SuiData, SuiMoveObject, SuiMovePackage, SuiMoveFunctionArgTypesResponse, SuiMoveFunctionArgType, SuiMoveFunctionArgTypes, SuiMoveNormalizedModules, SuiMoveNormalizedModule, SuiMoveModuleId, SuiMoveNormalizedStruct, SuiMoveStructTypeParameter, SuiMoveNormalizedField, SuiMoveNormalizedFunction, SuiMoveVisibility, SuiMoveTypeParameterIndex, SuiMoveAbilitySet, SuiMoveNormalizedType, SuiMoveNormalizedTypeParameterType, SuiMoveNormalizedStructType, SuiObject, ObjectStatus, ObjectType, GetOwnedObjectsResponse, GetObjectDataResponse, ObjectDigest, ObjectId, SequenceNumber, MoveEvent, PublishEvent, TransferObjectEvent, DeleteObjectEvent, NewObjectEvent, SuiEvent, MoveEventField, EventType, SuiEventFilter, SuiEventEnvelope, SuiEvents, SubscriptionId, SubscriptionEvent, TransferObject, SuiTransferSui, SuiChangeEpoch, Pay, ExecuteTransactionRequestType, TransactionKindName, SuiTransactionKind, SuiTransactionData, EpochId, GenericAuthoritySignature, AuthorityQuorumSignInfo, CertifiedTransaction, GasCostSummary, ExecutionStatusType, ExecutionStatus, OwnedObjectRef, TransactionEffects, SuiTransactionResponse, SuiCertifiedTransactionEffects, SuiExecuteTransactionResponse, GatewayTxSeqNumber, GetTxnDigestsResponse, GetTxnDigestsResponse__DEPRECATED, PaginatedTransactionDigests, TransactionQuery, Ordering, MoveCall, SuiJsonValue, EmptySignInfo, AuthorityName, AuthoritySignature, TransactionBytes, SuiParsedMergeCoinResponse, SuiParsedSplitCoinResponse, SuiParsedPublishResponse, SuiPackage, SuiParsedTransactionResponse, DelegationData, DelegationSuiObject, TransferObjectTx, TransferSuiTx, PayTx, PublishTx, ObjectArg, CallArg, StructTag, TypeTag, MoveCallTx, Transaction, TransactionKind, TransactionData } from "./index";
+import { TransactionDigest, SuiAddress, ObjectOwner, SuiObjectRef, SuiObjectInfo, ObjectContentFields, MovePackageContent, SuiData, SuiMoveObject, CoinDenominationInfoResponse, SuiMovePackage, SuiMoveFunctionArgTypesResponse, SuiMoveFunctionArgType, SuiMoveFunctionArgTypes, SuiMoveNormalizedModules, SuiMoveNormalizedModule, SuiMoveModuleId, SuiMoveNormalizedStruct, SuiMoveStructTypeParameter, SuiMoveNormalizedField, SuiMoveNormalizedFunction, SuiMoveVisibility, SuiMoveTypeParameterIndex, SuiMoveAbilitySet, SuiMoveNormalizedType, SuiMoveNormalizedTypeParameterType, SuiMoveNormalizedStructType, SuiObject, ObjectStatus, ObjectType, GetOwnedObjectsResponse, GetObjectDataResponse, ObjectDigest, ObjectId, SequenceNumber, MoveEvent, PublishEvent, TransferObjectEvent, DeleteObjectEvent, NewObjectEvent, SuiEvent, MoveEventField, EventType, SuiEventFilter, SuiEventEnvelope, SuiEvents, SubscriptionId, SubscriptionEvent, TransferObject, SuiTransferSui, SuiChangeEpoch, Pay, ExecuteTransactionRequestType, TransactionKindName, SuiTransactionKind, SuiTransactionData, EpochId, GenericAuthoritySignature, AuthorityQuorumSignInfo, CertifiedTransaction, GasCostSummary, ExecutionStatusType, ExecutionStatus, OwnedObjectRef, TransactionEffects, SuiTransactionResponse, SuiCertifiedTransactionEffects, SuiExecuteTransactionResponse, GatewayTxSeqNumber, GetTxnDigestsResponse, GetTxnDigestsResponse__DEPRECATED, PaginatedTransactionDigests, TransactionQuery, Ordering, MoveCall, SuiJsonValue, EmptySignInfo, AuthorityName, AuthoritySignature, TransactionBytes, SuiParsedMergeCoinResponse, SuiParsedSplitCoinResponse, SuiParsedPublishResponse, SuiPackage, SuiParsedTransactionResponse, DelegationData, DelegationSuiObject, TransferObjectTx, TransferSuiTx, PayTx, PublishTx, ObjectArg, CallArg, StructTag, TypeTag, MoveCallTx, Transaction, TransactionKind, TransactionData } from "./index";
 
 export function isTransactionDigest(obj: any, _argumentName?: string): obj is TransactionDigest {
     return (
@@ -112,6 +112,18 @@ export function isSuiMoveObject(obj: any, _argumentName?: string): obj is SuiMov
     )
 }
 
+export function isCoinDenominationInfoResponse(obj: any, _argumentName?: string): obj is CoinDenominationInfoResponse {
+    return (
+        (obj !== null &&
+            typeof obj === "object" ||
+            typeof obj === "function") &&
+        isTransactionDigest(obj.coinType) as boolean &&
+        (typeof obj.basicUnit === "undefined" ||
+            isTransactionDigest(obj.basicUnit) as boolean) &&
+        isSuiMoveTypeParameterIndex(obj.decimalNumber) as boolean
+    )
+}
+
 export function isSuiMovePackage(obj: any, _argumentName?: string): obj is SuiMovePackage {
     return (
         (obj !== null &&

sdk/typescript/src/types/objects.ts

@@ -36,6 +36,18 @@ export type SuiMoveObject = {
   has_public_transfer?: boolean;
 };
 
+export const MIST_PER_SUI: BigInt = BigInt(1000000000);
+
+export type CoinDenominationInfoResponse = {
+  /** Coin type like "0x2::sui::SUI" */
+  coinType: string;
+  /** min unit, like MIST */
+  basicUnit?: string;
+  /** number of zeros in the denomination,
+   * e.g., 9 here for SUI. */
+  decimalNumber: number;
+}
+
 export type SuiMovePackage = {
   /** A mapping from module name to disassembled Move bytecode */
   disassembled: MovePackageContent;