suidouble 1.14.2 → 1.14.3

package/index.js

@@ -4,7 +4,10 @@ import SuiTestScenario from './lib/SuiTestScenario.js';
 import SuiObject from './lib/SuiObject.js';
 import SuiUtils from './lib/SuiUtils.js';
 import SuiLocalTestValidator from './lib/SuiLocalTestValidator.js';
-import  { Transaction, Commands } from '@mysten/sui/transactions';
+import SuiMemoryObjectStorage from './lib/SuiMemoryObjectStorage.js';
+import SuiCoin from './lib/SuiCoin.js';
+import SuiCoins from './lib/SuiCoins.js';
+import { Transaction, Commands } from '@mysten/sui/transactions';
 import { bcs } from '@mysten/sui/bcs';
 
 const txInput = SuiUtils.txInput;
@@ -22,4 +25,7 @@ export {
     SuiUtils,
     txInput,
     bcs,
+    SuiMemoryObjectStorage,
+    SuiCoin,
+    SuiCoins,
 };

package/lib/SuiCoin.js

@@ -13,9 +13,18 @@ import { Commands, Transaction } from '@mysten/sui/transactions';
  * @property {string} symbol - Symbol for the token
  * @property {string} [id] - Meta id
  * @property {string} [type] - Coin type string
+ * 
+ * 
+ * @typedef SuidoubleCoinBalance
+ * @type {object}
+ * @property {SuiCoin} coin
+ * @property {string} coinType
+ * @property {number} coinObjectCount
+ * @property {bigint} totalBalance
+ * @property {Object.<string,string>} lockedBalance
+ * 
  */
 
-
 /** Coin metadata object */
 export default class SuiCoin {
 
@@ -53,38 +62,86 @@ export default class SuiCoin {
 
     /**
      * Normalize amount based on .decimals. Pass a string with a dot ('5.22', '0.0005') to convert it to units. No worries about loading metadata first.
-     * @param {String|Number|BigInt} amount 
-     * @returns {BigInt}
+     * @param {String|Number|bigint} amount 
+     * @returns {Promise.<bigint>}
      */
     async lazyNormalizeAmount(amount) {
         await this.getMetadata();
         return this.normalizeAmount(amount);
     }
 
-    amountToString(amount) {
+    /**
+     * Get readable representation of amount value (system one, bigint or converted from bigint, NOT the '1.99' etc) 
+     * based on coin decimals metadata ( so it expects metadata to be loaded or set).
+     * 
+     * @param {Object} params - format parameters
+     * @param {boolean} params.withAbbr - append K, M, B, T for large amounts. Suiet-style
+     * @param {boolean|string} params.separateThousands - separate thousands, by ',' or by specific delimeter
+     * 
+     * @returns {string}
+     */
+    amountToString(amount, options = {}) {
         if (!this.decimals) {
             throw new Error('Please load coin metadata first');
         }
 
+        const withAbbr = !!options.withAbbr;
+        const separateThousands = options.separateThousands;
+
         const str = (''+BigInt(amount)).padStart(this.decimals + 1,'0');
         const ind = str.length - this.decimals;
         let asFloatString = str.substring(0, ind) + '.' + str.substring(ind);
 
-        /// yep, I can't find a better way to strip extra 0 at the end. All regexes are not ok. Ping me if you have a good one
-        let i = asFloatString.length - 1;
-        let haveNotMetNoZero = false;
-        while (i > 0 && !haveNotMetNoZero) {
-            if (asFloatString.substring(i, i+1) === '0' && asFloatString.substring(i-1, i) !== '.') {
-                asFloatString = asFloatString.substring(0, i);
-            } else {
-                haveNotMetNoZero = true;
+        if (asFloatString.includes('.')) {
+            asFloatString = asFloatString.replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '');
+            if (!asFloatString.includes('.')) {
+                asFloatString = '' + asFloatString + '.0';
+            }
+        }
+
+        if (withAbbr) {
+            const asBig = BigInt(Math.floor(Number(asFloatString)));
+
+            if (asBig > 1000n) {
+                if (asBig < 1000000n) return this.formatWithAbbr(asBig, 1000n, 'K');
+                if (asBig >= 1000000n && asBig < 1000000000n) return this.formatWithAbbr(asBig, 1000000n, 'M');
+                if (asBig >= 1000000000n && asBig < 1000000000000n) return this.formatWithAbbr(asBig, 1000000000n, 'B');
+                if (asBig >= 1000000000000n) return this.formatWithAbbr(asBig, 1000000000000n, 'T');
             }
-            i--;
+        }
+
+        if (separateThousands) {
+            // asFloatString has '.' anyway ( see above )
+            const [integerPart, decimalPart] = asFloatString.split('.'); // Split into integer and decimal parts
+            const separator = (typeof separateThousands === 'string') ? separateThousands : ',';
+            const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+            asFloatString = '' + formattedInteger + '.' + decimalPart;
         }
 
         return asFloatString;
     }
 
+    
+    /**
+     * Format large amounts
+     * 
+     * thanks @bruceeewong and @suiet
+     * 
+     * @param {bigint} amount 
+     * @param {bigint} measureUnit 
+     * @param {string} abbrSymbol 
+     * 
+     * @returns {string}
+     */
+    formatWithAbbr(amount, measureUnit, abbrSymbol) {
+        let showAmount = (''+(Number(amount) / Number(measureUnit / 1000n)));
+        showAmount = showAmount.padEnd(4, '0');
+
+        const result = Intl.NumberFormat('en-US').format(Number(showAmount));
+        return result.replace(',', '.') + abbrSymbol;
+    }
+
+
     get suiMaster() {
         return this._suiCoins.suiMaster;
     }
@@ -140,6 +197,7 @@ export default class SuiCoin {
     /**
      * set predefined coin metadata so it will not be fetched from RPC
      * @param {CoinMeta} meta
+     * 
      * @returns {boolean} if processed ok
      */
     setMetadata(meta) {
@@ -152,11 +210,25 @@ export default class SuiCoin {
         return false;
     }
 
+    /**
+     * Load coin metadata from the blockchain. As a good pattern, it's better to have metadata hard-coded or cached
+     * and set via suiMaster.suiCoins.setCoinMetas(...)  
+     * 
+     * @returns {Promise.<boolean>}
+     */
     async getMetadata() {
         if (this._metadata) {
             return this._metadata;
         }
 
+        if (this.__getMetadataPromise) {
+            return await this.__getMetadataPromise();
+        }
+
+        // be sure it asyncs in 1 thread
+        this.__getMetadataResolver = null;
+        this.__getMetadataPromise = new Promise((res)=>{ this.__getMetadataResolver = res; });
+
         let result = null;
         try {
             result = await this.suiMaster.client.getCoinMetadata({
@@ -173,9 +245,17 @@ export default class SuiCoin {
             this._exists = true;
         }
 
-        return this._metadata;
+        this.__getMetadataResolver(true);
+
+        return true;
     }
 
+    /**
+     * Get coin balance of the wallet
+     * @param {string} owner
+     * 
+     * @returns {Promise.<bigint>}
+     */
     async getBalance(owner) {
         const coins = [];
         let result = null;
@@ -208,7 +288,8 @@ export default class SuiCoin {
      * @param {string} owner - address of the owner
      * @param {BigInt|string} amount - amount of coin. BigIng or String to be normalized via Coin decimals, "0.05" for 0.05 sui
      * @param {boolean} addEmptyCoins - attach coins == 0 to the list
-     * @returns {TransactionObjectArgument}
+     * 
+     * @returns {Promise.<TransactionObjectArgument>}
      */
     async coinOfAmountToTxCoin(txb, owner, amount, addEmptyCoins = false) {
         const normalizedAmount = await this.lazyNormalizeAmount(amount);

package/lib/SuiCoins.js

@@ -5,6 +5,7 @@ import { normalizeStructTag } from "@mysten/sui/utils";
 
 /**
  * @typedef {import("./SuiCoin.js").CoinMeta} CoinMeta
+ * @typedef {import("./SuiCoin.js").SuidoubleCoinBalance} SuidoubleCoinBalance
  * @typedef {import("./SuiMaster.js").default} SuiMaster
  */
 
@@ -79,6 +80,42 @@ export default class SuiCoins extends SuiCommonMethods {
         return processedCount;
     }
 
+    /**
+     * Get all CoinBalance[] for the specific address or connected address
+     * 
+     * @param {Object} params
+     * @param {string?} params.owner - owner address, if skipped - will query for connected wallet address
+     * 
+     * @returns {Promise.<Array.<SuidoubleCoinBalance>>}
+     */
+    async getAllBalances(params = {}) {
+        let owner = params.owner;
+        if (!owner) {
+            owner = this._suiMaster.address;
+        }
+
+        /** @type {Array.<SuidoubleCoinBalance>} */
+        const ret = [];
+
+        const nativeCoinBalances = await this._suiMaster.client.getAllBalances({
+                owner,
+            });
+
+        for (const nativeCoinBalance of nativeCoinBalances) {
+            /** @type {SuidoubleCoinBalance} */
+            const coinBalance = {
+                coin: this.get(nativeCoinBalance.coinType),
+                coinType: nativeCoinBalance.coinType,
+                coinObjectCount: nativeCoinBalance.coinObjectCount,
+                totalBalance: BigInt(nativeCoinBalance.totalBalance),
+                lockedBalance: nativeCoinBalance.lockedBalance,                
+            };
+            ret.push(coinBalance);
+        }
+
+        return ret;
+    }
+
     /**
      * normalize coinType string to sui's coin type. As extra, may take 'sui' or 'SUI' as the type and return type for it
      * @param {string} coinType
@@ -106,6 +143,7 @@ export default class SuiCoins extends SuiCommonMethods {
      * Return instance of SuiCoin of specific type
      * 
      * @param {string} coinType - MoveType, or 'SUI' as helper
+     * 
      * @returns {SuiCoin}
      */
     get(coinType) {

package/lib/SuiMaster.js

@@ -102,6 +102,7 @@ export default class SuiMaster extends SuiCommonMethods {
         }
 
         // we are differient single instances of object storage by provider name (so we can separate like devnet-testnet entities if needed)
+        /** @type {SuiMemoryObjectStorage} */
         this._objectStorage = SuiMemoryObjectStorage.instanceOf(this._providerName, {
             debug: this._debug,
             suiMaster: this,
@@ -111,6 +112,7 @@ export default class SuiMaster extends SuiCommonMethods {
 
         this._packages = {};
 
+        /** @type {SuiCoins} */
         this._suiCoins = new SuiCoins({
             suiMaster: this,
             debug: this._debug,
@@ -161,6 +163,11 @@ export default class SuiMaster extends SuiCommonMethods {
         return SuiEvent;
     }
 
+    /**
+     * Storage storing all objects interacted by this suiMaster
+     * 
+     * @type {SuiMemoryObjectStorage}
+     */
     get objectStorage() {
         return this._objectStorage;
     }

package/lib/SuiMemoryObjectStorage.js

@@ -1,10 +1,29 @@
 import SuiCommonMethods from './SuiCommonMethods.js';
-
+import SuiObject from './SuiObject.js';
+
+/**
+ * Class to work with SuiObject's in bulk
+ * 
+ * Sample usage:
+ * ```
+ * suiMemoryObjectStorage.push(id);
+ * suiMemoryObjectStorage.push(suiObject);
+ * await suiMemoryObjectStorage.fetchObjects();
+ * suiMemoryObjectStorage.byAddress(id);
+ * ```
+ */
 export default class SuiMemoryObjectStorage extends SuiCommonMethods {
+    /**
+     * SuiMemoryObjectStorage constructor
+     * @param {Object} params - Initialization parameters
+     * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     */
     constructor(params = {}) {
         super(params);
 
         this._suiMaster = params.suiMaster;
+
+        /** @type {Object.<string, SuiObject>} */
         this._objects = {};
     }
 
@@ -44,14 +63,29 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
         return mostRecentObject;
     }
 
-    push(object) {
-        if (object.address) {
-            this._objects[object.address] = object;
+    /**
+     * @param {SuiObject | string} suiObjectOrId 
+     * 
+     * @returns {SuiObject | null}
+     */
+    push(suiObjectOrId) {
+        if (suiObjectOrId && suiObjectOrId.address) {
+            const /** @type {SuiObject} */ obj = suiObjectOrId;
+            this._objects[obj.address] = obj;
+
+            return obj;
+        } else if (suiObjectOrId && (''+suiObjectOrId).indexOf('0x') === 0) {
+            if (this._objects[suiObjectOrId]) {
+                return this._objects[suiObjectOrId];
+            }
 
-            return true;
+            const obj = new SuiObject({id: suiObjectOrId, suiMaster: this._suiMaster});
+            this._objects[obj.address] = obj;
+
+            return obj;
         }
 
-        return false;
+        return null;
     }
 
     byAddress(address) {
@@ -125,6 +159,13 @@ export default class SuiMemoryObjectStorage extends SuiCommonMethods {
 
     static _instances = {};
 
+    /**
+     * @param {string} validatorId - just a string for single instance identifier
+     * @param {Object} params - Initialization parameters
+     * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * 
+     * @returns {SuiMemoryObjectStorage}
+     */
     static instanceOf(validatorId, params = {}) {
         if (SuiMemoryObjectStorage._instances[validatorId]) {
             return SuiMemoryObjectStorage._instances[validatorId];

package/lib/SuiPackage.js

@@ -501,7 +501,7 @@ export default class SuiPackage extends SuiObject {
      * @returns Boolean true on success
      */
     async build(params = {}) {
-        this.log('builing a package...');
+        this.log('building a package...');
 
         const path = this._path;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suidouble",
-  "version": "1.14.2",
+  "version": "1.14.3",
   "description": "Set of provider, package and object classes for javascript representation of Sui Move smart contracts. Use same code for publishing, upgrading, integration testing, interaction with smart contracts and integration in browser web3 dapps",
   "main": "index.js",
   "type": "module",
@@ -22,8 +22,8 @@
   "author": "suidouble (https://github.com/suidouble)",
   "license": "Apache-2.0",
   "dependencies": {
-    "@mysten/sui": "^1.14.2",
-    "@polymedia/coinmeta": "^0.0.16",
+    "@mysten/sui": "^1.14.3",
+    "@polymedia/coinmeta": "^0.0.17",
     "@wallet-standard/core": "^1.0.3",
     "websocket": "^1.0.35"
   },

package/test/coins.test.js

@@ -5,6 +5,8 @@ import { SuiMaster, SuiLocalTestValidator, Transaction } from '../index.js';
 const { test } = t;
 
 let suiLocalTestValidator = null;
+
+/** @type {SuiMaster} */
 let suiMaster = null;
 
 test('spawn local test node', async t => {
@@ -33,13 +35,6 @@ test('type is normalized for SUI', async t => {
     const suiCoin5 = suiMaster.suiCoins.get('2::sui::SUI');
     const suiCoin6 = suiMaster.suiCoins.get('0000000000000000000000000000000000000000000000000000000000000002::sui::SUI');
 
-    console.log(suiCoin1.coinType);
-    console.log(suiCoin2.coinType);
-    console.log(suiCoin3.coinType);
-    console.log(suiCoin4.coinType);
-    console.log(suiCoin5.coinType);
-    console.log(suiCoin6.coinType);
-
     t.ok(suiCoin1.coinType == suiCoin2.coinType);
     t.ok(suiCoin1.coinType == suiCoin3.coinType);
     t.ok(suiCoin1.coinType == suiCoin4.coinType);
@@ -67,6 +62,9 @@ test('string representation works ok', async t => {
     const toDisplay2 = suiCoin.amountToString(1); // 1 mist
     t.equal(toDisplay2, '0.000000001');
 
+    const toDisplay1000 = suiCoin.amountToString(1000); // 1000 mist
+    t.equal(toDisplay1000, '0.000001');
+
     const toDisplay3 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000) + BigInt(1)); // 1000 SUI + 1 mist
     t.equal(toDisplay3, '1000.000000001');
 
@@ -74,6 +72,95 @@ test('string representation works ok', async t => {
     t.equal(toDisplay4, '999.999999999');
 });
 
+
+test('string representation (withAbbr) works ok', async t => {
+    const suiCoin = suiMaster.suiCoins.get('sui');
+    await suiCoin.getMetadata();
+
+    // it should dispaly the same on the low amounts:
+
+    const toDisplay1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI, {withAbbr: true});
+    t.equal(toDisplay1, '1.0');
+
+    const toDisplay2 = suiCoin.amountToString(1, {withAbbr: true}); // 1 mist
+    t.equal(toDisplay2, '0.000000001');
+
+    const toDisplay1000 = suiCoin.amountToString(1000, {withAbbr: true}); // 1000 mist
+    t.equal(toDisplay1000, '0.000001');
+
+    const toDisplay3 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000) + BigInt(1), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplay3, '1000.000000001');
+
+    const toDisplay4 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000) - BigInt(1), {withAbbr: true}); // 1000 SUI - 1 mist
+    t.equal(toDisplay4, '999.999999999');
+
+    // things are getting interesting starting from '1001.0'
+
+    const toDisplayK1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1001) + BigInt(1), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplayK1, '1.001K');
+    const toDisplayK2 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(2000), {withAbbr: true}); 
+    t.equal(toDisplayK2, '2.000K');
+    const toDisplayK3 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(999900), {withAbbr: true}); 
+    t.equal(toDisplayK3, '999.900K');
+
+    const toDisplayM1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000) + BigInt(1), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplayM1, '1.000M');
+    const toDisplayM2 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(2000000) + BigInt(900), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplayM2, '2.000M');
+
+    const toDisplayB1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000000) + BigInt(1), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplayB1, '1.000B');
+
+    const toDisplayT1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000000000) + BigInt(1), {withAbbr: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplayT1, '1.000T');
+});
+
+
+test('string representation (separateThousands) works ok', async t => {
+    const suiCoin = suiMaster.suiCoins.get('sui');
+    await suiCoin.getMetadata();
+
+    // it should dispaly the same on the low amounts:
+
+    const toDisplay1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI, {separateThousands: true});
+    t.equal(toDisplay1, '1.0');
+
+    const toDisplay2 = suiCoin.amountToString(1, {separateThousands: true}); // 1 mist
+    t.equal(toDisplay2, '0.000000001');
+
+    const toDisplay1000 = suiCoin.amountToString(1000, {separateThousands: true}); // 1000 mist
+    t.equal(toDisplay1000, '0.000001');
+
+    const toDisplay3 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000) + BigInt(1), {separateThousands: true}); // 1000 SUI + 1 mist
+    t.equal(toDisplay3, '1,000.000000001');
+
+    const toDisplay4 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000) - BigInt(1), {separateThousands: true}); // 1000 SUI - 1 mist
+    t.equal(toDisplay4, '999.999999999');
+
+    // things are getting interesting starting from '1001.0'
+
+    const toDisplayK1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1001) + BigInt(1), {separateThousands: true});
+    t.equal(toDisplayK1, '1,001.000000001');
+    const toDisplayK2 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(2000), {separateThousands: true}); 
+    t.equal(toDisplayK2, '2,000.0');
+    const toDisplayK3 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(999900), {separateThousands: true}); 
+    t.equal(toDisplayK3, '999,900.0');
+
+    const toDisplayM1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000) + BigInt(1), {separateThousands: true});
+    t.equal(toDisplayM1, '1,000,000.000000001');
+    const toDisplayM2 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(2000000) + BigInt(900), {separateThousands: true}); 
+    t.equal(toDisplayM2, '2,000,000.0000009');
+
+    const toDisplayB1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000000) + BigInt(1), {separateThousands: true}); 
+    t.equal(toDisplayB1, '1,000,000,000.000000001');
+
+    const toDisplayT1 = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000000000) + BigInt(1), {separateThousands: true}); 
+    t.equal(toDisplayT1, '1,000,000,000,000.000000001');
+
+    const toDisplayT1q = suiCoin.amountToString(suiMaster.MIST_PER_SUI * BigInt(1000000000000) + BigInt(1), {separateThousands: ' '}); 
+    t.equal(toDisplayT1q, '1 000 000 000 000.000000001');
+});
+
 test('you have no SUI on the fresh node', async t => {
     const suiCoin = suiMaster.suiCoins.get('sui');
     const balance = await suiCoin.getBalance(suiMaster.address);
@@ -88,6 +175,22 @@ test('have some after requesting from faucet', async t => {
     t.ok(balance > BigInt(0));
 });
 
+test('have some in balance query', async t => {
+    const balances = await suiMaster.suiCoins.getAllBalances();
+
+    let ok = false;
+    for (const balance of balances) {
+        if (balance.coin.isSUI()) {
+            if (balance.totalBalance > 0n) {
+                ok = true;
+            }
+        }
+    }
+
+    t.ok(ok);
+});
+
+
 test('getting coin objects for a transaction', async t => {
     const suiCoin = suiMaster.suiCoins.get('sui');
 
@@ -111,7 +214,6 @@ test('getting coin objects for a transaction', async t => {
 });
 
 
-
 test('stops local test node', async t => {
     await SuiLocalTestValidator.stop();
 });