[TypeScript SDK] Add methods for the CoinRead endpoints (#7507)

Author: xydas97

.changeset/lucky-lobsters-joke.md

@@ -0,0 +1,5 @@
+---
+"@mysten/sui.js": minor
+---
+
+Add methods for the CoinRead endpoints

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

@@ -45,10 +45,13 @@ import {
   normalizeSuiObjectId,
   SuiTransactionAuthSignersResponse,
   CoinMetadataStruct,
+  PaginatedCoins,
   GetObjectDataResponse,
   GetOwnedObjectsResponse,
   DelegatedStake,
   ValidatorMetaData,
+  CoinBalance,
+  CoinSupply,
 } from '../types';
 import { DynamicFieldPage } from '../types/dynamic_fields'
 import {
@@ -169,6 +172,103 @@ export class JsonRpcProvider extends Provider {
     return undefined;
   }
 
+  async requestSuiFromFaucet(
+    recipient: SuiAddress,
+    httpHeaders?: HttpHeaders
+  ): Promise<FaucetResponse> {
+    if (!this.endpoints.faucet) {
+      throw new Error('Faucet URL is not specified');
+    }
+    return requestSuiFromFaucet(this.endpoints.faucet, recipient, httpHeaders);
+  }
+
+  // Coins
+  async getCoins(
+    owner: SuiAddress,
+    coinType: String | null = null,
+    cursor: ObjectId | null = null,
+    limit: number | null = null
+  ) : Promise<PaginatedCoins> {
+    try {
+      if (!owner || !isValidSuiAddress(normalizeSuiAddress(owner))) {
+        throw new Error('Invalid Sui address');
+      }
+      return await this.client.requestWithType(
+        'sui_getCoins',
+        [owner, coinType, cursor, limit],
+        PaginatedCoins,
+        this.options.skipDataValidation
+      );
+    } catch (err) {
+      throw new Error(
+        `Error getting coins for owner ${owner}: ${err}`
+      );
+    }
+  }
+
+  async getAllCoins(
+    owner: SuiAddress,
+    cursor: ObjectId | null = null,
+    limit: number | null = null
+  ) : Promise<PaginatedCoins> {
+    try {
+      if (!owner || !isValidSuiAddress(normalizeSuiAddress(owner))) {
+        throw new Error('Invalid Sui address');
+      }
+      return await this.client.requestWithType(
+        'sui_getAllCoins',
+        [owner, cursor, limit],
+        PaginatedCoins,
+        this.options.skipDataValidation
+      );
+    } catch (err) {
+      throw new Error(
+        `Error getting all coins for owner ${owner}: ${err}`
+      )
+    }
+  }
+
+  async getBalance(
+    owner: SuiAddress,
+    coinType: String | null = null,
+  ) : Promise<CoinBalance> {
+    try {
+      if (!owner || !isValidSuiAddress(normalizeSuiAddress(owner))) {
+        throw new Error('Invalid Sui address');
+      }
+      return await this.client.requestWithType(
+        'sui_getBalance',
+        [owner, coinType],
+        CoinBalance,
+        this.options.skipDataValidation
+      );
+    } catch (err) {
+      throw new Error(
+        `Error getting balance for coin type ${coinType} for owner ${owner}: ${err}`
+      )
+    }
+  }
+
+  async getAllBalances(
+    owner: SuiAddress
+  ) : Promise<CoinBalance[]> {
+    try {
+      if (!owner || !isValidSuiAddress(normalizeSuiAddress(owner))) {
+        throw new Error('Invalid Sui address');
+      }
+      return await this.client.requestWithType(
+        'sui_getAllBalances',
+        [owner],
+        array(CoinBalance),
+        this.options.skipDataValidation
+      );
+    } catch (err) {
+      throw new Error(
+        `Error getting all balances for owner ${owner}: ${err}`
+      )
+    }
+  }
+
   async getCoinMetadata(coinType: string): Promise<CoinMetadata> {
     try {
       return await this.client.requestWithType(
@@ -182,14 +282,21 @@ export class JsonRpcProvider extends Provider {
     }
   }
 
-  async requestSuiFromFaucet(
-    recipient: SuiAddress,
-    httpHeaders?: HttpHeaders
-  ): Promise<FaucetResponse> {
-    if (!this.endpoints.faucet) {
-      throw new Error('Faucet URL is not specified');
+  async getTotalSupply(
+    coinType: String
+  ) : Promise<CoinSupply> {
+    try {
+      return await this.client.requestWithType(
+        'sui_getTotalSupply',
+        [coinType],
+        CoinSupply,
+        this.options.skipDataValidation
+      );
+    } catch (err) {
+      throw new Error(
+        `Error fetching total supply for Coin type ${coinType}: ${err}`
+      );
     }
-    return requestSuiFromFaucet(this.endpoints.faucet, recipient, httpHeaders);
   }
 
   // RPC endpoint
@@ -337,6 +444,9 @@ export class JsonRpcProvider extends Provider {
     return objects.filter((obj: SuiObjectInfo) => Coin.isSUI(obj));
   }
 
+  /**
+   * @deprecated The method should not be used
+   */
   async getCoinBalancesOwnedByAddress(
     address: SuiAddress,
     typeArg?: string
@@ -359,7 +469,9 @@ export class JsonRpcProvider extends Provider {
     typeArg: string = SUI_TYPE_ARG,
     exclude: ObjectId[] = []
   ): Promise<GetObjectDataResponse[]> {
-    const coins = await this.getCoinBalancesOwnedByAddress(address, typeArg);
+    const coinsStruct = await this.getCoins(address, typeArg);
+    const coinIds = coinsStruct.data.map((c) => c.coinObjectId);
+    const coins = await this.getObjectBatch(coinIds);
     return (await Coin.selectCoinsWithBalanceGreaterThanOrEqual(
       coins,
       amount,
@@ -373,7 +485,9 @@ export class JsonRpcProvider extends Provider {
     typeArg: string = SUI_TYPE_ARG,
     exclude: ObjectId[] = []
   ): Promise<GetObjectDataResponse[]> {
-    const coins = await this.getCoinBalancesOwnedByAddress(address, typeArg);
+    const coinsStruct = await this.getCoins(address, typeArg);
+    const coinIds = coinsStruct.data.map((c) => c.coinObjectId);
+    const coins = await this.getObjectBatch(coinIds);
     return (await Coin.selectCoinSetWithCombinedBalanceGreaterThanOrEqual(
       coins,
       amount,

sdk/typescript/src/providers/provider.ts

@@ -35,6 +35,9 @@ import {
   TransactionEffects,
   CoinMetadata,
   DevInspectResults,
+  PaginatedCoins,
+  CoinBalance,
+  CoinSupply,
 } from '../types';
 
 import { DynamicFieldPage } from '../types/dynamic_fields';
@@ -51,15 +54,6 @@ export abstract class Provider {
    */
   abstract getRpcApiVersion(): Promise<RpcApiVersion | undefined>;
 
-  /**
-   * Fetch CoinMetadata for a given coin type
-   *
-   * @param coinType fully qualified type names for the coin (e.g.,
-   * 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
-   *
-   */
-  abstract getCoinMetadata(coinType: string): Promise<CoinMetadata>;
-
   // Faucet
   /**
    * Request gas tokens from a faucet server
@@ -82,6 +76,63 @@ export abstract class Provider {
     params: Array<any>
   ) : Promise<any>;
 
+  // Coins
+  /**
+   * Get all Coin<`coin_type`> objects owned by an address. 
+   * @param coinType optional fully qualified type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::sui::SUI if not specified.
+   * @param cursor optional paging cursor
+   * @param limit maximum number of items per page
+   */
+  abstract getCoins(
+    owner: SuiAddress,
+    coinType: String | null,
+    cursor: ObjectId | null,
+    limit: number | null
+  ) : Promise<PaginatedCoins>;
+
+  /**
+   * Get all Coin objects owned by an address.
+   * @param cursor optional paging cursor
+   * @param limt maximum number of items per page
+   */
+  abstract getAllCoins(
+    owner: SuiAddress,
+    cursor: ObjectId | null,
+    limit: number | null
+  ) : Promise<PaginatedCoins>;
+
+  /**
+   * Get the total coin balance for one coin type, owned by the address owner.
+   * @param coinType optional fully qualified type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::sui::SUI if not specified.
+   */
+  abstract getBalance(
+    owner: SuiAddress,
+    coinType: String | null
+  ) : Promise<CoinBalance>;
+
+  /**
+   * Get the total coin balance for all coin type, owned by the address owner.
+   */
+  abstract getAllBalances(
+    owner: SuiAddress
+  ) : Promise<CoinBalance[]>;
+
+  /**
+   * Fetch CoinMetadata for a given coin type
+   * @param coinType fully qualified type names for the coin (e.g.,
+   * 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
+   *
+   */
+  abstract getCoinMetadata(coinType: string): Promise<CoinMetadata>;
+
+  /**
+   *  Fetch total supply for a coin
+   * @param coinType fully qualified type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::sui::SUI if not specified.
+   */
+  abstract getTotalSupply(
+    coinType: string
+  ) : Promise<CoinSupply>;
+
   // Objects
   /**
    * Get all objects owned by an address
@@ -98,8 +149,7 @@ export abstract class Provider {
   ): Promise<SuiObjectInfo[]>;
 
   /**
-   * Convenience method for getting all coins objects owned by an address
-   * @param typeArg optional argument for filter by coin type, e.g., '0x2::sui::SUI'
+   * @deprecated The method should not be used
    */
   abstract getCoinBalancesOwnedByAddress(
     address: string,

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

@@ -36,6 +36,9 @@ import {
   TransactionEffects,
   CoinMetadata,
   DevInspectResults,
+  PaginatedCoins,
+  CoinBalance,
+  CoinSupply,
 } from '../types';
 import { Provider } from './provider';
 
@@ -47,10 +50,6 @@ export class VoidProvider extends Provider {
     throw this.newError('getRpcApiVersion');
   }
 
-  getCoinMetadata(_coinType: string): Promise<CoinMetadata> {
-    throw new Error('getCoinMetadata');
-  }
-
   // Governance
   async getReferenceGasPrice(): Promise<number> {
     throw this.newError('getReferenceGasPrice');
@@ -71,6 +70,47 @@ export class VoidProvider extends Provider {
     throw this.newError('call');
   }
 
+  // Coins
+  async getCoins(
+    _owner: SuiAddress,
+    _coinType: String | null,
+    _cursor: ObjectId | null,
+    _limit: number | null
+  ) : Promise<PaginatedCoins> {
+    throw this.newError('getCoins');
+  }
+
+  async getAllCoins(
+    _owner: SuiAddress,
+    _cursor: ObjectId | null,
+    _limit: number | null
+  ) : Promise<PaginatedCoins> {
+    throw this.newError('getAllCoins');
+  }
+
+  async getBalance(
+    _owner: string, 
+    _coinType: String | null
+    ): Promise<CoinBalance> {
+      throw this.newError('getBalance');
+  }
+
+  async getAllBalances(
+    _owner: string, 
+    ): Promise<CoinBalance[]> {
+      throw this.newError('getAllBalances');
+  }
+
+  async getCoinMetadata(_coinType: string): Promise<CoinMetadata> {
+    throw new Error('getCoinMetadata');
+  }
+
+  async getTotalSupply(
+    _coinType: string
+  ) : Promise<CoinSupply> {
+    throw new Error('getTotalSupply');
+  }
+
   // Objects
   async getObjectsOwnedByAddress(_address: string): Promise<SuiObjectInfo[]> {
     throw this.newError('getObjectsOwnedByAddress');
@@ -82,6 +122,9 @@ export class VoidProvider extends Provider {
     throw this.newError('getGasObjectsOwnedByAddress');
   }
 
+  /**
+   * @deprecated The method should not be used
+   */
   async getCoinBalancesOwnedByAddress(
     _address: string,
     _typeArg?: string