suidouble 0.0.37 → 0.0.39

package/README.md

@@ -8,10 +8,12 @@ Set of provider, package and object classes for javascript representation of Sui
     - [Attaching a package](#attaching-a-package)
     - [Interacting with smart contract](#interacting-with-smart-contract)
     - [SuiObject](#suiobject)
+    - [Fetching objects](#fetching-objects)
     - [Fetching Events](#fetching-events)
     - [Subscribe to Events](#subscribing-to-events)
     - [Executing smart contract method](#executing-smart-contract-method)
-    - [Fetching objects](#fetching-objects)
+    - [Sending sui / coins with smart contract methods](#sending-sui--coins-with-smart-contract-methods)
+    - [Composing transaction block yourself](#composing-transaction-block-yourself)
 - [Publishing the package](#publishing-the-package)
 - [Upgrading the package](#upgrading-the-package)
 - [Writing Sue Move intergration tests](#sui-move-integration-testing)
@@ -205,15 +207,65 @@ const res = await contract.moveCall('chat', 'post', ['0x10cded4f9df05e37b44e3be2
     }
 ```
 
-If you need to transfer some SUI as part of executing contract method, you can use a magic parameter in form of {type: 'SUI', amount: 400000000000n} where 400000000000 is the amount of MIST you want to send. SuiPackageModule will convert this amount to Coin object using Transactions.SplitCoins method.
+##### sending sui / coins with smart contract methods
+
+If you need to transfer some SUI/coins as part of executing contract method, you can use a magic parameter in form of:
+
+```javascript
+{type: 'SUI', amount: 400000000000n} 
+// 400000000000 MISTs, if amount is BigInt, it's used in decimal items
+{type: 'SUI', amount: '0.2'}         
+// 0.2 SUI           , if amount is String, it's translated to decimals, using coin metadata in a lazy way
+{type: '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN', amount: '1'}
+// 1 USDC
+{type: '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN', amount: '99.99'}
+// 99.99 USDT
+```
 
-`amount: 400000000000n`, `amount: '400000000000'`, `amount: 400000000000` will work too
+So executing
 
 ```javascript
-const moveCallResult = await contract.moveCall('suidouble_chat', 'post_pay', [chatShopObjectId, {type: 'SUI', amount: 400000000000n}, messageText, 'metadata']);
+const params = [
+    chatShopObjectId,
+    {type: '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN', amount: '9.99'},
+    messageText,
+];
+const moveCallResult = await contract.moveCall('suidouble_chat', 'post_pay', params);
+```
+
+will send 9.99 USDT as the second parameter of the package method. Suidouble will convert needed coins using Sui's SplitCoins and MergeCoins internally to match amount you expect to send.
+
+Some smart contracts requires clients to send coins in form of vectors. This is covered too, just pass magic parameter if the form of an array with one element:
+
+```javascript
+const params = [
+    chatShopObjectId,
+    [{type: '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN', amount: '9.99'}],
+    messageText,
+];
+```
+
+Don't forget to test transactions sending real money on devnet/testnet first!
+
+
+##### composing transaction block yourself
+
+If you need more flexebility, there's always an option to construct the transaction block yourself:
+
+```javascript
+const { TransactionBlock, Transactions } = require('suidobule'); // this exposes classes from the "@mysten/sui.js", so you don't have to import them separately
+
+const txb = new TransactionBlock();
+txb.moveCall({
+    target: `package_id::module_id::method_name`,
+    arguments: [
+        txb.pure(something),
+        txb.object(someid),
+    ],
+});
+const moveCallResult = await contract.moveCall('suidouble_chat', 'post_pay', {tx: txb});
 ```
 
-@todo: sending other Coins
 
 ##### fetching objects
 
@@ -369,8 +421,6 @@ Take a look at [unit tests](test) code for some inspiration.
 
 ### Todo
 
-- subscribe to events
-- sending other coins as contract methods execution
 - suiobject invalidation/fetching optimization
 - better documentation
 - unit tests coverage to 90%+

package/index.js

@@ -3,6 +3,7 @@ const SuiInBrowser = require('./lib/SuiInBrowser.js');
 const SuiTestScenario = require('./lib/SuiTestScenario.js');
 const SuiObject = require('./lib/SuiObject.js');
 const SuiLocalTestValidator = require('./lib/SuiLocalTestValidator.js');
+const sui = require('@mysten/sui.js');
 
 module.exports = {
     SuiMaster,
@@ -11,4 +12,7 @@ module.exports = {
     SuiTestScenario,
     SuiLocalTestValidator,
     MIST_PER_SUI: SuiMaster.MIST_PER_SUI,
+
+    TransactionBlock: sui.TransactionBlock,
+    Transactions: sui.Transactions,
 };

package/lib/SuiCoin.js

@@ -0,0 +1,257 @@
+const { Transactions } = require('@mysten/sui.js/transactions');
+
+const safeList = {
+    'sui:mainnet': {
+        '0xa198f3be41cda8c07b3bf3fee02263526e535d682499806979a111e88a5a8d0f::coin::COIN': 'CELO',
+        '0x027792d9fed7f9844eb4839566001bb6f6cb4804f66aa2da6fe1ee242d896881::coin::COIN': 'tBTC',
+        '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN': 'USDCeth',
+        '0xe32d3ebafa42e6011b87ef1087bbc6053b499bf6f095807b9013aff5a6ecd7bb::coin::COIN': 'USDCarb',
+        '0x909cba62ce96d54de25bec9502de5ca7b4f28901747bbf96b76c2e63ec5f1cba::coin::COIN': 'USDCbnb',
+        '0xcf72ec52c0f8ddead746252481fb44ff6e8485a39b803825bde6b00d77cdb0bb::coin::COIN': 'USDCpol',
+        '0xb231fcda8bbddb31f2ef02e6161444aec64a514e2c89279584ac9806ce9cf037::coin::COIN': 'USDCsol',
+        '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN': 'USDT',
+        '0x1e8b532cca6569cab9f9b9ebc73f8c13885012ade714729aa3b450e0339ac766::coin::COIN': 'WAVAX',
+        '0xb848cce11ef3a8f62eccea6eb5b35a12c4c2b1ee1af7755d02d7bd6218e8226f::coin::COIN': 'WBNB',
+        '0x027792d9fed7f9844eb4839566001bb6f6cb4804f66aa2da6fe1ee242d896881::coin::COIN': 'WBTC',
+        '0xaf8cd5edc19c4512f4259f0bee101a40d41ebed738ade5874359610ef8eeced5::coin::COIN': 'WETH',
+        '0x6081300950a4f1e2081580e919c210436a1bed49080502834950d31ee55a2396::coin::COIN': 'WFTM',
+        '0x66f87084e49c38f76502d17f87d17f943f183bb94117561eb573e075fdc5ff75::coin::COIN': 'WGLMR',
+        '0xdbe380b13a6d0f5cdedd58de8f04625263f113b3f9db32b3e1983f49e2841676::coin::COIN': 'WMATIC',
+        '0xb7844e289a8410e50fb3ca48d69eb9cf29e27d223ef90353fe1bd8e27ff8f3f8::coin::COIN': 'WSOL',
+        '0x2::sui::SUI': 'SUI',
+    },
+};
+
+class SuiCoin {
+    constructor(params = {}) {
+        this._coinType = params.coinType;
+        this._suiCoins = params.suiCoins;
+
+        this._exists = null;
+        this._metadata = null;
+    }
+
+    /**
+     * Normalize amount based on .decimals. Pass a string with a dot ('5.22', '0.0005') to convert it to units
+     * always use a dot, event for '1.0' or '100.0'.
+     * @param {String|Number|BigInt} amount 
+     * @returns {BigInt}
+     */
+    normalizeAmount(amount) {
+        if (typeof(amount) == 'string' && amount.indexOf('.') !== -1) {
+            if (!this.decimals) {
+                throw new Error('Please load coin metadata first');
+            }
+
+            return BigInt(Math.floor(parseFloat(amount, 10) * Math.pow(10, this.decimals)));
+        }
+
+        return BigInt(amount);
+    }
+
+    /**
+     * 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}
+     */
+    async lazyNormalizeAmount(amount) {
+        await this.getMetadata();
+        return this.normalizeAmount(amount);
+    }
+
+    amountToString(amount) {
+        if (!this.decimals) {
+            throw new Error('Please load coin metadata first');
+        }
+
+        const str = (''+BigInt(amount)).padStart(this.decimals + 1,'0');
+        const ind = str.length - this.decimals;
+        return str.substring(0, ind) + '.' + str.substring(ind);
+    }
+
+    get suiMaster() {
+        return this._suiCoins.suiMaster;
+    }
+
+    static safeList(connectedChain) {
+        return safeList[connectedChain];
+    }
+
+    get coinType() {
+        if (this._coinType.indexOf('0x') === 0) {
+            return this._coinType;
+        }
+
+        return '0x'+this._coinType;
+    }
+
+    get decimals() {
+        if (this.metadata) {
+            return this.metadata.decimals;
+        }
+        return undefined;
+    }
+
+    get metadata() {
+        return this._metadata;
+    }
+
+    get safeList() {
+        if (this.suiMaster && this.suiMaster.connectedChain) {
+            if (safeList[this.suiMaster.connectedChain]) {
+                return safeList[this.suiMaster.connectedChain];
+            }
+        }
+
+        return {};
+    }
+
+    get isSafe() {
+        if (this.safeList[this.coinType]) {
+            return true;
+        }
+
+        return false;
+    }
+
+    get symbol() {
+        if (this.safeList[this.coinType]) {
+            return this.safeList[this.coinType];
+        }
+
+        if (this.metadata) {
+            return this.metadata.symbol;
+        }
+
+        return null;
+    }
+
+    get name() {
+        return this.metadata.name;
+    }
+
+    isSUI() {
+        return this._coinType.toLowerCase().indexOf('sui') > -1;
+    }
+
+    async getMetadata() {
+        if (this._metadata) {
+            return this._metadata;
+        }
+
+        let result = null;
+        try {
+            result = await this.suiMaster.provider.getCoinMetadata({
+                    coinType: this.coinType,
+                });
+        } catch (e) {
+            console.error(e);
+            result = null;
+        }
+        if (!result) {
+            this._exists = false;
+        } else {
+            this._metadata = result;
+        }
+
+        return this._metadata;
+    }
+
+    async getBalance(owner) {
+        const coins = [];
+        let result = null;
+        let cursor = null;
+        do {
+            result = await this.suiMaster.provider.getCoins({
+                owner: owner,
+                coinType: this.coinType,
+                limit: 50,
+                cursor: cursor,
+            });
+            coins.push(...result.data);
+
+            cursor = result.nextCursor;
+        } while (result.hasNextPage);
+
+        let totalAmount = BigInt(0);
+        for (const coin of coins) {
+            totalAmount = totalAmount + BigInt(coin.balance);
+        }
+
+        return totalAmount;
+    }
+
+    async coinOfAmountToTxCoin(txb, owner, amount, addEmptyCoins = false) {
+        const expectedAmountAsBigInt = BigInt(amount);
+        const coinIds = await this.coinObjectsEnoughForAmount(owner, expectedAmountAsBigInt, addEmptyCoins);
+
+        if (!coinIds || !coinIds.length) {
+            throw new Error('you do not have enough coins of type '+this.coinType);
+        }
+
+        if (coinIds.length == 1) {
+            // only one coin object enough to cover the expense
+            if (this.isSUI()) {
+                const coinInput = txb.add(Transactions.SplitCoins(txb.gas, [txb.pure(expectedAmountAsBigInt)]));
+                return coinInput;
+            } else {
+                // some other coin
+                const coinInput = txb.add(Transactions.SplitCoins(txb.object(coinIds[0]), [txb.pure(expectedAmountAsBigInt)]));
+                return coinInput;
+            }
+        } else {
+            // few coin objects to merge
+            const coinIdToMergeIn = coinIds.shift();
+            txb.add(Transactions.MergeCoins(txb.object(coinIdToMergeIn), coinIds.map((id)=>{return txb.object(id);})));
+            const coinInputSplet = txb.add(Transactions.SplitCoins(txb.object(coinIdToMergeIn), [txb.pure(expectedAmountAsBigInt)]));
+
+            return coinInputSplet;
+        }
+    }
+
+    async coinObjectsEnoughForAmount(owner, expectedAmount, addEmptyCoins = false) {
+        const expectedAmountAsBigInt = BigInt(expectedAmount);
+
+        const coinIds = [];
+        const coins = [];
+
+        let result = null;
+        let cursor = null;
+        do {
+            result = await this.suiMaster.provider.getCoins({
+                owner: owner,
+                coinType: this.coinType,
+                limit: 50,
+                cursor: cursor,
+            });
+            coins.push(...result.data);
+
+            cursor = result.nextCursor;
+        } while (result.hasNextPage);
+
+        coins.sort((a, b) => {
+            // From big to small
+            return Number(b.balance) - Number(a.balance);
+        });
+
+        let totalAmount = BigInt(0);
+        for (const coin of coins) {
+            if (totalAmount <= expectedAmountAsBigInt) {
+                coinIds.push(coin.coinObjectId);
+                totalAmount = totalAmount + BigInt(coin.balance);//  totalAmount.add(coin.balance);
+            } else {
+                if (addEmptyCoins && BigInt(coin.balance) == 0n) {
+                    coinIds.push(coin.coinObjectId);
+                }
+            }
+        }
+
+        if (totalAmount >= expectedAmountAsBigInt) {
+            return coinIds;
+        }
+
+        return null;
+    }
+}
+
+module.exports = SuiCoin;

package/lib/SuiCoins.js

@@ -0,0 +1,132 @@
+const SuiCoin = require('./SuiCoin.js');
+const SuiCommonMethods = require('./SuiCommonMethods.js');
+
+class SuiCoins extends SuiCommonMethods {
+    constructor(params = {}) {
+        super(params);
+        
+        this._suiMaster = params.suiMaster;
+        if (!this._suiMaster) {
+            throw new Error('suiMaster is required');
+        }
+        this._coins = {};
+
+        this._isInitialized = false;
+    }
+
+    get suiMaster() {
+        return this._suiMaster;
+    }
+
+    get coins() {
+        return this._coins;
+    }
+
+    /**
+     * Optional common initialized to get a list and metadata of all safe coins defined in SuiCoin.js
+     */
+    async init() {
+        if (this._isInitialized) {
+            return true;
+        }
+
+        const safeList = SuiCoin.safeList(this._suiMaster.connectedChain);
+        const metadataPromises = [];
+        for (const coinType in safeList) {
+            const normalizedCoinType = this.normalizeCoinType(coinType);
+            if (!this._coins[normalizedCoinType]) {
+                const suiCoin = new SuiCoin({
+                    coinType: normalizedCoinType,
+                    suiCoins: this,
+                });
+                console.log('adding coin with type', normalizedCoinType);
+                this._coins[normalizedCoinType] = suiCoin;
+
+                const metadataPromise = new Promise(async(res)=>{
+                    try {
+                        await suiCoin.getMetadata();
+                    } catch (e) {
+                        console.error(e);
+                    }
+
+                    res();
+                });
+                metadataPromises.push(metadataPromise);
+            }
+        }
+
+        await Promise.all(metadataPromises);
+
+        this._isInitialized = true;
+    }
+
+    normalizeCoinType(coinType) {
+        if (coinType.indexOf('::') == -1) {
+            if (coinType.toLowerCase() == 'sui') {
+                return '0x2::sui::SUI';
+            } else {
+                for (const key in this._coins) {
+                    if (key == coinType) {
+                        return this._coins[key].coinType;
+                    }
+                }
+
+                const safeList = SuiCoin.safeList(this._suiMaster.connectedChain);
+                for (const key in safeList) {
+                    if (safeList[key] == coinType) {
+                        return key;
+                    }
+                }
+            }
+
+            if (coinType.indexOf('0x') == -1) {
+                return '0x'+coinType+'::coin::COIN';
+            } else {
+                return ''+coinType+'::coin::COIN';
+            }
+        }
+
+        if (coinType.indexOf('0x') == -1) {
+            coinType = '0x'+coinType;
+        }
+
+        if (coinType == '0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI') {
+            return '0x2::sui::SUI';
+        }
+
+        return coinType;
+    }
+
+    get(coinType) {
+        const normalizedCoinType = this.normalizeCoinType(coinType); 
+        let suiCoin = this._coins[normalizedCoinType];
+        if (suiCoin) {
+            return suiCoin;
+        }
+
+        suiCoin = new SuiCoin({
+            coinType: normalizedCoinType,
+            suiCoins: this,
+        });
+
+        this._coins[normalizedCoinType] = suiCoin;
+
+        return suiCoin;
+    }
+
+    static _singleInstances = {};
+    static getSingleton(params = {}) {
+        const suiMaster = params.suiMaster;
+        const connectedChain = suiMaster.connectedChain;
+
+        if (SuiCoins._singleInstances[connectedChain]) {
+            return SuiCoins._singleInstances[connectedChain];
+        }
+
+        SuiCoins._singleInstances[connectedChain] = new SuiCoins(params);
+        return SuiCoins._singleInstances[connectedChain];
+    }
+
+};
+
+module.exports = SuiCoins;

package/lib/SuiMaster.js

@@ -7,6 +7,7 @@ const SuiPaginatedResponse = require('./SuiPaginatedResponse.js');
 const SuiObject = require('./SuiObject.js');
 const SuiTransaction = require('./SuiTransaction.js');
 const SuiEvent = require('./SuiEvent.js');
+const SuiCoins = require('./SuiCoins.js');
 
 class SuiMaster extends SuiCommonMethods {
     constructor(params = {}) {
@@ -103,6 +104,15 @@ class SuiMaster extends SuiCommonMethods {
         this._initialized = false;
 
         this._packages = {};
+
+        this._suiCoins = new SuiCoins({
+            suiMaster: this,
+            debug: this._debug,
+        });
+    }
+
+    get suiCoins() {
+        return this._suiCoins;
     }
 
     get MIST_PER_SUI() {
@@ -237,26 +247,23 @@ class SuiMaster extends SuiCommonMethods {
         return amount;
     }
 
-    async getBalance(coinType = '0x2::sui::SUI') {
+    /**
+     * Query the balance of specific coinType for an owner. If owner == null, returns balance of connected address owner
+     * 
+     * @param {String} coinType 
+     * @param {String|null} owner 
+     * @returns BigInt
+     */
+    async getBalance(coinType = '0x2::sui::SUI', owner = null) {
         await this.initialize();
 
-        this.log('requesting balance of coin', coinType, '...');
-
-        let res = null;
-        try {
-            res = await this._provider.getBalance({owner: this._address, coinType});
-        } catch (e) {
-            this.log('error', e);
-            res = null;
-        }
-
-        let ret = BigInt(0);
-        if (res && res.totalBalance) {
-            ret = BigInt(res.totalBalance);
+        let queryingBalanceOf = owner;
+        if (!queryingBalanceOf && this.address) {
+            queryingBalanceOf = this.address;
         }
 
-        this.log('balance of', coinType, 'is', ret);
-        return ret;
+        const suiCoin = this._suiCoins.get(coinType);
+        return await (suiCoin.getBalance(queryingBalanceOf));
     }
 
     // export type TransactionFilter =

package/lib/SuiPackageModule.js

@@ -115,29 +115,40 @@ class SuiPackageModule extends SuiCommonMethods {
     async moveCall(methodName, params) {
         await this._package.checkOnChainIfNeeded();
 
-        const tx = new sui.TransactionBlock();
-
-        const callArgs = [];
-
-        for (let param of params) {
-            if (param && param.type && param.amount && param.type === 'SUI') {
-                let amount = BigInt(param.amount);
-                const coin = tx.add(sui.Transactions.SplitCoins(tx.gas, [tx.pure(amount)]));
-                callArgs.push(coin);
-            } else if (param && Array.isArray(param) && param.length == 1 && param[0].type && param[0].amount && param[0].type === 'SUI') {
-                // vector<Coin<SUI>>
-                let amount = BigInt(param[0].amount);
-                const coin = tx.add(sui.Transactions.SplitCoins(tx.gas, [tx.pure(amount)]));
-                callArgs.push(tx.makeMoveVec({ objects: [coin]}));
-            } else {
-                callArgs.push(tx.pure(param));
+        let tx = null;
+        if (params.tx) {
+            tx = params.tx;
+        } else {
+            tx = new sui.TransactionBlock();
+
+            const callArgs = [];
+    
+            for (let param of params) {
+                if (param && param.type && param.amount) {
+                    const ownerAddress = this._suiMaster.address;
+
+                    const suiCoin = await this._suiMaster.suiCoins.get(param.type);
+                    const txCoinToSend = await suiCoin.coinOfAmountToTxCoin(tx, ownerAddress, param.amount);
+
+                    callArgs.push(txCoinToSend);
+                } else if (param && Array.isArray(param) && param.length == 1 && param[0].type && param[0].amount) {
+                    // vector<Coin<SUI>>
+                    const ownerAddress = this._suiMaster.address;
+
+                    const suiCoin = await this._suiMaster.suiCoins.get(param.type);
+                    const txCoinToSend = await suiCoin.coinOfAmountToTxCoin(tx, ownerAddress, param.amount);
+
+                    callArgs.push(tx.makeMoveVec({ objects: [txCoinToSend]}));
+                } else {
+                    callArgs.push(tx.pure(param));
+                }
             }
+            
+            tx.moveCall({
+                target: `${this._package.address}::${this._moduleName}::${methodName}`,
+                arguments: callArgs,
+            });
         }
-        
-        tx.moveCall({
-            target: `${this._package.address}::${this._moduleName}::${methodName}`,
-            arguments: callArgs,
-        });
 
         const result = await this._suiMaster._signer.signAndExecuteTransactionBlock({
             transactionBlock: tx,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suidouble",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "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",
   "scripts": {
@@ -21,7 +21,7 @@
   "author": "Jeka Kiselyov <jeka911@gmail.com> (https://github.com/jeka-kiselyov)",
   "license": "Apache-2.0",
   "dependencies": {
-    "@mysten/sui.js": "^0.37.1",
+    "@mysten/sui.js": "^0.39.0",
     "@wallet-standard/core": "^1.0.3"
   },
   "devDependencies": {