@verified-network/verified-sdk 1.5.6 → 1.5.8

package/.env

@@ -5,4 +5,5 @@ GENERAL_PAYMASTER_URL="https://paymaster.biconomy.io/api/v1"
 80001_PAYMASTER_API_KEY="aoDXoLOsa.b941e672-e98f-4d56-b9f6-733dca59a87e"
 # 5_CASH_TOKEN_ADDRESS="0x07865c6E87B9F70255377e024ace6630C1Eaa37F" //goerli(chainid 5) not workith biconomy
 80001_CASH_TOKEN_ADDRESS="0xda5289fcaaf71d52a80a254da614a192b693e977"
+11155111_PAYMASTER_API_KEY="BuFP2-5w-.5b3daf3a-d044-4dda-819c-4c4d8431df88"
 BICONOMY_REVERT_TOPIC="0x1c4fada7374c0a9ee8841fc38afe82932dc0f8e69012e927f061a8bae611a201"

package/README.md

@@ -1,34 +1,88 @@
 # The Verified SDK
+
 The Verified SDK provides access to the issuing, trading and servicing of tokenized securities on the Verified Network.
 
 # installing using npm
-```npm install @verified-network/verified-sdk```
+
+`npm install @verified-network/verified-sdk`
 
 # creating new wallet
+
 ```
 const {VerifiedWallet} = require('@verified-network/verified-sdk');
 let mnemonics = await VerifiedWallet.generateMnemonics()
 let wallet = await VerifiedWallet.importWallet(menmonics)
 ```
+
 # setProvider
+
+Provider can be set for wallet using 2 options:
+
+# using default providers
+
+Default providers are available for networks like: mainnet/homestead, ropsten, sepolia e.t.c and are mainly used for development(it is also robust enough for use in production)
+
 ```
 const {Provider} = require('@verified-network/verified-sdk');
-const defaultProvider = 'ropsten' // or any other network of your choice.
+const defaultProvider = 'sepolia' // or any other default provider network of your choice.
+Network/chain id(number) can be used in place of network name, for example:
+const defaultProvider = 11155111 // where number 11155111 is chain id for sepolia, any other chain id of default provider network can be used.
 let walletWithProvider = wallet.setProvider(
     Provider.defaultProvider(defaultProvider)
 )
 ```
+
+# using custom providers
+
+Verified Sdk supports Infura and Alchemy to provide custom providers for any network.
+
+```
+const {Provider} = require('@verified-network/verified-sdk');
+const network = 'sepolia' // or any other network of your choice.
+Network/chain id(number) can be used in place of network name, for example:
+const network = 11155111 // where number 11155111 is chain id for sepolia, any other chain id can be used.
+//For infura; to get api key and enable networks checout: https://www.infura.io/
+const INFURA_API_KEY = 'your infura api key'
+let walletWithProvider = wallet.setProvider(
+    Provider.infuraProvider(network, INFURA_API_KEY)
+)
+//For Alchemy;  to get api key and enable networks checout: https://www.alchemy.com/
+const ALCHEMY_KEY = 'your alchemy api key'
+let walletWithProvider = wallet.setProvider(
+    Provider.alchemyProvider(network, ALCHEMY_KEY)
+)
+```
+
 # interacting with Smart contracts
-```let clientContract = new ClientContract(wallet);```
+
+```
+cosnt {Client} = require('@verified-network/verified-sdk');
+let clientContract = new Client(walletWithProvider);
+```
 
 This will create an instance of Client contract and you can access all the functions within the clientContract using this object.
 
 Now you can call a function in clientContract like:
-```clientContract.setAccess("true")``` // to set the access to True/False.
+`clientContract.setAccess("true")` // to set the access to True/False.
+
+Some contracts requires additional parameters to create their instances, for example:
+
+```
+cosnt {SecurityContract, PrimaryIssueManager} = require('@verified-network/verified-sdk');
+// securityContract
+const securityContractAddress = 'security address for any verified security'
+let securityContract = new SecurityContract(walletWithProvider, securityContractAddress);
+
+//primaryIssueManager
+const primaryIssueManagerAddress = 'primary issue manager address'
+const primaryIssueManagerplatform = 'primary issue manager platform' //e.g 'balancer'
+let primaryIssueManagerContract = new PrimaryIssueManager(walletWithProvider, primaryIssueManagerAddress, primaryIssueManagerplatform);
+```
 
 Similarly you can create different Contracts instances available:
+
 ```
-ClientContract,
+Client,
 BondContract,
 CashContract,
 TokenContract,
@@ -46,17 +100,185 @@ DistributionContract
 ```
 
 # VerifiedContract
+
 src/contract/index.ts is the base class for all Contracts created.
 It has the logic to validate the Input, Sanitise the Input and Output, call the contract functions etc.
 All the contracts trigger smart contract calls and go through the callContract function.
 
 Optionally, all the contractCalls take in an additional parameter:
-```options?: { gasPrice: number, gasLimit: number }```
+`options?: { gasPrice: number, gasLimit: number }`
 You can configure the gasPrice and gasLimit using this parameter as the last parameter to the contractCall function.
-Example: ```this.callContract(FUNCTIONS.GETORDERS, originator, options)```
+Example: `this.callContract(FUNCTIONS.GETORDERS, originator, options)`
 Where, options = {gasPrice: XXX, gasLimit: YYY}
 
 # This is how you can integrate with any Dapp.
+
 1. Install and Import the SDK
 2. Create a wallet instance and fund it
-3. Create instances of the Contract that you want to interact with using the above wallet and call their functions.
+3. Create instances of the Contract that you want to interact with using the above wallet and call their functions.
+
+# Common Error(s) with Verified Sdk integration with Dapp
+
+Due to webpack version > 5 that no longer includes NodeJS polyfills by default, it is causing issues for developers that use React(create-react-app), React-native, Vite with webpack version > 5 to build applications with web3.js, ethers.js, alchemy libraries e.t.c. Many of this libraries and dependencies are used by Verified Sdk.
+
+There are various ways to solve this error, from updating webpack config to babel config e.t.c. and can be overwhelming for developers. Verified Network Team recommend ed using best solutions that are easy to use and beginner friendly.
+
+# How to resolve React error(s) with Verified Sdk integration
+
+Step 1: Install react-app-rewired
+with npm: `npm install --save-dev react-app-rewired`
+with yarn: `yarn add --dev react-app-rewired`
+
+Step 2: Install needed dependencies
+// with npm:  
+`npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process`
+// with yarn:
+`yarn add crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process`
+
+note: the above dependencies are needed dependencies to make verified sdk works, more dependencies can be added to handle any other nodeJs polyfills error.
+
+Step 3: Override create-react-app webpack config file
+In the root folder of your project, create a new file called 'config-overrides.js', and add the following code to it:
+
+```
+const webpack = require("webpack");
+module.exports = function override(config) {
+  const fallback = config.resolve.fallback || {};
+  Object.assign(fallback, {
+    crypto: require.resolve("crypto-browserify"),
+    stream: require.resolve("stream-browserify"),
+    assert: require.resolve("assert"),
+    http: require.resolve("stream-http"),
+    https: require.resolve("https-browserify"),
+    os: require.resolve("os-browserify"),
+    url: require.resolve("url"),
+    path: require.resolve("path-browserify"),
+    fs: false, //assumed fs module will not be used(to use fs module download dependency to handle it)
+  });
+  config.plugins = (config.plugins || []).concat([
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+      Buffer: ["buffer", "Buffer"],
+    }),
+  ]);
+  config.module.rules = [
+    ...config.module.rules,
+    {
+      test: /\.m?js/,
+      resolve: {
+        fullySpecified: false,
+      },
+    },
+  ]; // rules are optional can be customised to fit your usecase
+  config.resolve.fallback = fallback;
+  config.ignoreWarnings = [/Failed to parse source map/]; // optional can be customised to fit your usecase
+  return config;
+};
+```
+
+This 'config-overrides.js' code snippet is telling webpack how to resolve the missing dependencies that are needed to support web3, ethers libraries and wallet providers in the browser/server side.
+
+Step 4: Override package.json to use react-app-rewired
+Within the package.json file, replace react-scripts with react-app-rewired scripts for 'start', 'build', 'test'
+
+```
+"scripts": {
+  "start": "react-app-rewired start",
+  "build": "react-app-rewired build",
+  "test": "react-app-rewired test",
+  "eject": "react-scripts eject"
+ },
+```
+
+note: start changed from "react-scripts start" to "react-app-rewired start", build from "react-scripts build" to "react-app-rewired build" and test from "react-scripts test" to "react-app-rewired test" while eject remains the same.
+
+The polyfill node core module error should be fixed any missing NodeJS polyfills should be included in your app, and your app should work well with Verified Sdk
+
+# How to resolve Vite error(s) with Verified Sdk integration
+
+Step 1: install @esbuild-plugins/node-modules-polyfill and rollup-plugin-polyfill-node
+with npm: `npm i @esbuild-plugins/node-modules-polyfill rollup-plugin-polyfill-node`
+with yarn: `yarn add @esbuild-plugins/node-modules-polyfill rollup-plugin-polyfill-node`
+
+Step 2: Install needed dependencies
+with npm:  
+`npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process`
+with yarn:
+`yarn add crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process`
+
+Step 3: update vite.config.js file
+From the root folder of your project update 'vite.config.js' to resolve missing dependencies
+
+```
+import { NodeGlobalsPolyfillPlugin } from "@esbuild-plugins/node-globals-polyfill";
+import nodePolyfills from "rollup-plugin-polyfill-node";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  build: {
+    target: ["es2020"], //optional can be customised
+    rollupOptions: {
+      plugins: [nodePolyfills()],
+    },
+  },
+  resolve: {
+    alias: {
+      process: "process/browser",
+      stream: "stream-browserify",
+      zlib: "browserify-zlib",
+      util: "util/",
+      path: "path-browserify",
+      "@": resolve(__dirname, "./src"), //optional
+    },
+  },
+  optimizeDeps: {
+    esbuildOptions: {
+      // Node.js global to browser globalThis
+      define: {
+        global: "globalThis",
+      },
+      supported: {
+        bigint: true, //optional
+      },
+      // Enable esbuild polyfill plugins
+      plugins: [
+        NodeGlobalsPolyfillPlugin({
+          buffer: true,
+          protocolImports: true,
+        }),
+      ],
+    },
+  }
+});
+
+```
+
+This 'vite.config.js' code snippet is telling webpack how to resolve the missing dependencies that are needed to support web3, ethers libraries and wallet providers in the browser/server side.
+
+The polyfill node core module error should be fixed any missing NodeJS polyfills should be included in your app, and your app should work well with Verified Sdk.
+
+# Verified Sdk also provides ERC 4337-compliant solution and enable account abstraction using Biconomy Smart Accounts.
+
+Verified Sdk follows ERC 4337 standard and implement pseudo-transaction object(userOperation) to enable transaction sponsorship allowing smart contract creators to sponsor some set of transactions on smart contract for users when certain functions are called and allow multiple transaction to be called in batch
+
+With this unique feature of Verified Sdk creators can pay gas fee for users/entity interaction with smart contract in ERC 20 token or Native tokens(Eth, Matic e.t.c) and also enable users/entity interacting with the contract to pay for gas fee using ERC 20 tokens.
+
+# How Verified Sdk Gasless transactions work
+
+For every transactions/interactions with verified smart contracts, various checks are made to determine if the transaction will be gasless(will be sponsored) or not. For gasless transactions, contract creators have pre deposited certain amount of native tokens(Eth, Matic e.t.c) or ERC 20 tokens(USDC, VUSDC e.t.c) on Biconomy paymaster dashboard to cover gas fees for set of functions on smart contract.
+
+# Verified Sdk checks for every transaction:
+
+    # Check 1: is Biconomy Paymaster supported for the network/chain the contract is on?
+    If yes:
+    # Check 2: is the smart contract called part of smart contracts that support gasless or Erc 20 gas payments?
+    If yes:
+    # Check 3: is the function called parts of functions selected to support gasless or ERC 20 payments?
+    If yes:
+    # Check 4: what type of paymaster was set? Gasless or ERC 20
+        If gasless:
+        # Check 5: is the deposited gas enough to pay for transaction?
+        if yes: Transaction is sposored(user does not pay for gas fee)
+        if ERC 20:
+        # User pay for transaction using ERC 20 tokens
+    # If no: User will pay for transaction using native tokens(Eth, Matic e.t.c)

package/dist/contract/index.js

@@ -1,18 +1,13 @@
 // SPDX-License-Identifier: BUSL-1.1
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VerifiedContract = exports.DATATYPES = void 0;
-const dotenv_1 = require("dotenv");
 const ethers_1 = require("ethers");
-const web3_1 = __importDefault(require("web3"));
 const account_1 = require("@biconomy/account");
 const modules_1 = require("@biconomy/modules");
 const bundler_1 = require("@biconomy/bundler");
 const paymaster_1 = require("@biconomy/paymaster");
-dotenv_1.config();
+const constants_1 = require("../utils/constants");
 var STATUS;
 (function (STATUS) {
     STATUS[STATUS["SUCCESS"] = 0] = "SUCCESS";
@@ -143,17 +138,25 @@ class VerifiedContract {
     tempOutput(data) {
         const response = { hash: '', result: [] };
         data.forEach(async (element) => {
-            if (element.hash !== undefined || element.transactionHash)
+            if (element.hash !== undefined || element.transactionHash) {
                 return response.hash = element.hash || element.transactionHash;
-            if (element._isBigNumber)
+            }
+            else if (element._isBigNumber) {
                 return response.result.push(element.toString());
-            if (ethers_1.utils.isAddress(element))
+            }
+            else if (ethers_1.utils.isAddress(element)) {
                 return response.result.push(element);
+            }
             //if (utils.isBytesLike(element)) return response.result.push(this.sanitiseOutput(DATATYPES.BYTE32, element))
-            if (ethers_1.utils.isBytesLike(element))
+            else if (ethers_1.utils.isBytesLike(element)) {
+                return response.result.push(element);
+            }
+            else if (typeof element === 'boolean') {
                 return response.result.push(element);
-            if (typeof element === 'boolean' || (await this.validateInput(DATATYPES.ADDRESS, element)))
+            }
+            else {
                 return response.result.push(element);
+            }
         });
         return response;
     }
@@ -167,7 +170,7 @@ class VerifiedContract {
     /** Checks if a contract support gasless transaction */
     supportsGasless(chainId) {
         let isSupported = false;
-        const contractPaymasterUrl = process.env[`${chainId}_PAYMASTER_API_KEY`];
+        const contractPaymasterUrl = constants_1.PaymasterConstants[`${chainId}_PAYMASTER_API_KEY`];
         if (contractPaymasterUrl && contractPaymasterUrl.length > 0)
             isSupported = true;
         return isSupported;
@@ -176,16 +179,14 @@ class VerifiedContract {
     async createSmartAccount(chainId) {
         //create bundler instance
         const bundler = new bundler_1.Bundler({
-            bundlerUrl: `${process.env.BUNDLER_URL_FIRST_SECTION}/${chainId}/${process.env.BUNDLER_URL_SECTION_SECTION}`,
+            bundlerUrl: `${constants_1.PaymasterConstants.BUNDLER_URL_FIRST_SECTION}/${chainId}/${constants_1.PaymasterConstants[`${chainId}_URL_SECOND_SECTION`]}`,
             chainId: chainId,
             entryPointAddress: account_1.DEFAULT_ENTRYPOINT_ADDRESS,
         });
-        // console.log("bd: ", bundler);
         //create paymaster instance
         const paymaster = new paymaster_1.BiconomyPaymaster({
-            paymasterUrl: `${process.env.GENERAL_PAYMASTER_URL}/${chainId}/${process.env[`${chainId}_PAYMASTER_API_KEY`]}`,
+            paymasterUrl: `${constants_1.PaymasterConstants.GENERAL_PAYMASTER_URL}/${chainId}/${constants_1.PaymasterConstants[`${chainId}_PAYMASTER_API_KEY`]}`,
         });
-        // console.log("pm: ", paymaster);
         const module = await modules_1.ECDSAOwnershipValidationModule.create({
             signer: this.signer,
             moduleAddress: modules_1.DEFAULT_ECDSA_OWNERSHIP_MODULE,
@@ -200,7 +201,6 @@ class VerifiedContract {
             activeValidationModule: module,
         });
         // console.log("address", await biconomyAccount.getAccountAddress());
-        //return smart account
         return biconomyAccount;
     }
     /** Constructs and call function with ethers.js */
@@ -221,10 +221,7 @@ class VerifiedContract {
              */
             let fn = this.contract[functionName];
             let _res = await fn(...args, ...options);
-            //console.log('_res', _res)
-            //console.log('_res.value.toString()',_res.value.toString())
             let _resp = _res.wait !== undefined ? await _res.wait(_res) : _res;
-            //console.log('_resp', _resp)
             res.response = this.tempOutput(this.convertToArray(ethers_1.utils.deepCopy(_resp)));
             res.status = STATUS.SUCCESS;
             res.message = "";
@@ -240,7 +237,7 @@ class VerifiedContract {
         }
     }
     /** Constructs and call function as userop for biconomy gassless(sponsored/erc20 mode) */
-    async callFunctionAsUserOp(smartAccount, userOp) {
+    async callFunctionAsUserOp(smartAccount, userOp, functionName, ...args) {
         //send userops transaction and construct transaction response
         let res = {};
         try {
@@ -250,7 +247,7 @@ class VerifiedContract {
                 res.response = {
                     hash: transactionDetails.receipt.transactionHash,
                     result: [],
-                }; //TODO: update response
+                }; //TODO: update result on response
                 res.status = STATUS.SUCCESS;
                 res.message = "";
                 return res;
@@ -258,23 +255,27 @@ class VerifiedContract {
             else {
                 const logs = transactionDetails.receipt.logs;
                 let reason = "";
-                const provider = this.contract.provider;
                 logs.map((log) => {
-                    if (log.topics.includes(process.env.BICONOMY_REVERT_TOPIC)) {
-                        const web3 = new web3_1.default(provider);
-                        reason = web3.utils.hexToAscii(log.data);
+                    if (log.topics.includes(constants_1.PaymasterConstants.BICONOMY_REVERT_TOPIC)) {
+                        try {
+                            reason = ethers_1.utils.formatBytes32String(log.data);
+                        }
+                        catch (err) {
+                            reason = reason;
+                        }
                     }
                 });
                 throw Error(`execution reverted: ${reason}`);
             }
         }
         catch (err) {
-            console.log(err);
-            res.status = STATUS.ERROR;
-            res.reason = err.reason;
-            res.message = err.message;
-            res.code = err.code;
-            return res;
+            console.error("gasless transaction failed with error: ", err);
+            console.log("will use ethers....");
+            // res.status = STATUS.ERROR;
+            // res.reason = err.reason;
+            // res.message = err.message;
+            // res.code = err.code;
+            return await this.callFunctionWithEthers(functionName, ...args);
         }
     }
     async callContract(functionName, ...args) {
@@ -310,7 +311,15 @@ class VerifiedContract {
                 data: _res.data,
             };
             //build userop transaction
-            let partialUserOp = await smartAccount.buildUserOp([tx1]);
+            let partialUserOp;
+            try {
+                partialUserOp = await smartAccount.buildUserOp([tx1]);
+            }
+            catch (err) {
+                console.log("error while buiding gassless transaction: ", err);
+                console.log("will use ethers....");
+                return await this.callFunctionWithEthers(functionName, ...args);
+            }
             //query paymaster for sponsored mode to get neccesary params and update userop
             const biconomyPaymaster = smartAccount.paymaster;
             try {
@@ -331,7 +340,7 @@ class VerifiedContract {
                             paymasterAndDataResponse.preVerificationGas;
                     }
                 }
-                return await this.callFunctionAsUserOp(smartAccount, partialUserOp);
+                return await this.callFunctionAsUserOp(smartAccount, partialUserOp, functionName, ...args);
             }
             catch (err) {
                 console.log("sponsored failed will try erc20");
@@ -341,7 +350,7 @@ class VerifiedContract {
                     //get fee quote for network cash token
                     const feeQuotesResponse = await biconomyPaymaster.getPaymasterFeeQuotesOrData(partialUserOp, {
                         mode: paymaster_1.PaymasterMode.ERC20,
-                        tokenList: [process.env[`${chainId}_CASH_TOKEN_ADDRESS`]],
+                        tokenList: [constants_1.PaymasterConstants[`${chainId}_CASH_TOKEN_ADDRESS`]],
                     });
                     // console.log("fq: ", feeQuotesResponse);
                     const feeQuotes = feeQuotesResponse.feeQuotes;
@@ -372,7 +381,7 @@ class VerifiedContract {
                     const _paymasterAndDataWithLimits = await biconomyPaymaster.getPaymasterAndData(finalUserOp, paymasterServiceData);
                     finalUserOp.paymasterAndData =
                         _paymasterAndDataWithLimits.paymasterAndData;
-                    return await this.callFunctionAsUserOp(smartAccount, finalUserOp);
+                    return await this.callFunctionAsUserOp(smartAccount, finalUserOp, functionName, ...args);
                 }
                 catch (_err) {
                     //if erc20 mode didn't work use ethers.js

package/dist/utils/constants.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymasterConstants = void 0;
+//Todo: add more network paymaster details for gasless
+exports.PaymasterConstants = {
+    BUNDLER_URL_FIRST_SECTION: "https://bundler.biconomy.io/api/v2",
+    GENERAL_PAYMASTER_URL: "https://paymaster.biconomy.io/api/v1",
+    BICONOMY_REVERT_TOPIC: "0x1c4fada7374c0a9ee8841fc38afe82932dc0f8e69012e927f061a8bae611a201",
+    "11155111_PAYMASTER_API_KEY": "BuFP2-5w-.5b3daf3a-d044-4dda-819c-4c4d8431df88",
+    "11155111_URL_SECOND_SECTION": "nJPK7B3ru.dd7f7861-190d-41bd-af80-6877f74b8f44",
+    // "137_PAYMASTER_API_KEY": "lDHvYk50N.30a2522e-0a9d-444b-b949-19194c1f237a",
+    // "137_URL_SECOND_SECTION": "dewj2189.wh1289hU-7E49-45ic-af80-JkuxGCYRV",
+    "80001_PAYMASTER_API_KEY": "3B83DXSwj.3b20bc68-6e09-4bf2-bff5-5a0d11989389",
+    "80001_URL_SECOND_SECTION": "nJPK7B3ru.dd7f7861-190d-41bd-af80-6877f74b8f44"
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verified-network/verified-sdk",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "description": "An SDK to develop applications on the Verified Network",
   "repository": {
     "type": "git",
@@ -38,12 +38,10 @@
     "@biconomy/modules": "^3.1.1",
     "@biconomy/paymaster": "^3.1.1",
     "ethereumjs-tx": "^2.1.2",
-    "ethers": "^5.7.2",
-    "web3": "1.10.2"
+    "ethers": "^5.7.2"
   },
   "devDependencies": {
     "@types/mocha": "^10.0.6",
-    "dotenv": "^10.0.0",
     "mocha": "^10.2.0",
     "ts-node": "^10.9.1",
     "typescript": "^4.3.4"