koilib 2.0.0 → 2.4.0

package/README.md

@@ -60,13 +60,13 @@ You can also load it directly to the browser by downloading the bunble file loca
 With Typescript import the library
 
 ```typescript
-import { Signer, Contract, Provider, utils } from "koilib";
+import { Signer, Contract, Provider, Serializer, utils } from "koilib";
 ```
 
 With Javascript import the library with require
 
 ```javascript
-const { Signer, Contract, Provider, utils } = require("koilib");
+const { Signer, Contract, Provider, Serializer, utils } = require("koilib");
 ```
 
 There are 4 principal classes:
@@ -74,6 +74,8 @@ There are 4 principal classes:
 - **Signer**: Class containing the private key. It is used to sign.
 - **Provider**: Class to connect with the RPC node.
 - **Contract**: Class defining the contract to interact with.
+- **Serializer**: Class with the protocol buffers definitions to
+  serialize/deserialize data types.
 
 The following code shows how to sign a transaction, broadcast
 a transaction, and read contracts.
@@ -92,11 +94,20 @@ a transaction, and read contracts.
   });
   const koin = koinContract.functions;
 
+  // optional: preformat input/output
+  koinContract.abi.methods.balanceOf.preformatInput = (owner) => ({ owner });
+  koinContract.abi.methods.balanceOf.preformatOutput = (res) =>
+    utils.formatUnits(res.value, 8);
+  koinContract.abi.methods.transfer.preformatInput = (input) => ({
+    from: signer.getAddress(),
+    to: input.to,
+    value: utils.parseUnits(input.value, 8),
+  });
+
   // Transfer
   const { transaction, transactionResponse } = await koin.transfer({
-    from: signer.getAddress(),
     to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
-    value: "1000",
+    value: "10.0001",
   });
   console.log(`Transaction id ${transaction.id} submitted`);
 
@@ -105,9 +116,7 @@ a transaction, and read contracts.
   console.log(`Transaction mined. Block id: ${blockId}`);
 
   // read the balance
-  const { result } = await koin.balanceOf({
-    owner: signer.getAddress(),
-  });
+  const { result } = await koin.balanceOf(signer.getAddress());
   console.log(balance.result);
 })();
 ```
@@ -161,6 +170,7 @@ const abiToken = {
       inputs: "balance_of_arguments",
       outputs: "balance_of_result",
       readOnly: true,
+      defaultOutput: { value: "0" },
     },
     transfer: {
       entryPoint: 0x62efa292,
@@ -177,6 +187,38 @@ const abiToken = {
 };
 ```
 
+Note that this example uses "defaultOutput" for the method
+"balanceOf". This is used when the smart contract returns an
+empty response (for instance when there are no balance records
+for a specific address) and you require a default output in
+such cases.
+
+## FAQ
+
+1. Can this library be used to create smart contracts?
+
+   No. You need to install [koinos-cdt](https://github.com/koinos/koinos-cdt) for
+   this purpose.
+
+2. Can this library be used to deploy smart contracts?
+
+   Yes. If you already have the contract compiled as a .wasm file you can use
+   the Contract class to load the bytecode and deploy it.
+
+3. Can this library be used to create the ABI for any smart contract?
+
+   For the ABI you need the .proto file and the library
+   [protobufjs](https://www.npmjs.com/package/protobufjs). Then follow the format
+   for the ABI as described in the previous section. It's important to note that
+   this ABI is not the same ABI used in [koinos-cli](https://docs.koinos.io/architecture/contract-abi.html).
+   In particular, descriptors use different format (koilib using json format, cli
+   using binary format).
+
+4. Can this library be used to interact with smart contracts?
+
+   Yes. You can use it to call readOnly functions, or send transactions
+   to the contract by calling write functions.
+
 ## Documentation
 
 The complete documentation can be found at https://joticajulian.github.io/koilib/