Koinos Group did a great job by launching Koinos Testnet V2, which include new features like the use of protobuffers, and the VM Manager.
In my previous work I released a javascript library to interact with the first testnet. However, now the version 2 uses a complete different way of serializing data: Protobuffers. And this is the principal reason they had to launch a new blockchain. Now the challenge was to upgrade the library and make it compatible with the Testnet V2. I'm happy to announce that the upgrade of the JS library is already done and it also includes new features that make it easier to use than ever before.
But before going to the details of the new library, let's discuss about protobuffers.
What is protobuffers? and why it is important? Protobuffers is a protocol to transform data into bytes in order to send messages between different services. We also want to send only the useful information.
For instance, let's say I have the following message to make a tranfer: {"from":"alice", "to": "bob", "value":1000}. If we assume that both sender and receiver of the message know how is the structure of a message then the words "from", "to", and "value" are redundant, thus they can be omitted during the transmission. We actually need just the important data, that is "alice", "bob", and 1000. Protobuffers will join these 3 values, put the corresponding delimiters of each one and create a set of bytes. The receiver, which already knows the structure of a transfer, will transform these bytes again in {"from":"alice", "to": "bob", "value":1000}.
Koinos Testnet V1 used Koinos Types, a protocol with the same idea as Protobuffers, with some differences in the way the bytes were created. However, Koinos Types required extra work in order to give support to different programming languages. Koinos Group started with C++ and Go, and I contributed with the version for Typescript. Protobuffers, on the other hand, has been written already for many different languages. The languages in the official page of Google are Java, Python, Objective-C, C++, Kotlin, Dart, Go, Ruby, and C#. But the community around the world have been created it for other languages like Javascript and Rust. So, in conclusion, Protobuffers gives more flexibility to create microservices in different programming languages.
The Koinos Library for Javascript has now support for protobuffers, and it comes with new characteristics. The principal one is the way the contract functions are accessed. In the previous version a transfer was created in this way
// Old way to make a transfer - Koilib V1
const opTransfer = wallet.encodeOperation({
name: "transfer",
args: {
from: "19T7nHRLK9iAUVjPkbsenfUzvbCdpBnARy",
to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
value: BigInt(1000),
},
});
const tx = await wallet.newTransaction({
getNonce: true,
operations: [opTransfer],
});
await wallet.signTransaction(tx);
await wallet.sendTransaction(tx);
In the new version we just call
// transfer - Koilib V2
await koin.transfer({
from: "19T7nHRLK9iAUVjPkbsenfUzvbCdpBnARy",
to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
value: "1000",
});
that's all. Behind this function several things happens, like the encoding using protobuffers, the creation of the operation, the creation of the transaction, the signature using the private key, and the connection with the JSON-RPC to broadcast the signed transaction.
This new design is inspired in the Ether.js library developed for Ethereum. There are 3 principal classes:
These 3 classes can work independently depending on the task you need to perform, but the common way to use the library is by linking the classes:
In this way you just use the contract instance, which internally will sign using the Signer and send to the blockchain using the Provider.
The library also includes the option to preformat the input or output of a contract function.
For instance, if in normal conditions we use the following function to read the balance
const { result } = await koin.balanceOf({
owner: "19T7nHRLK9iAUVjPkbsenfUzvbCdpBnARy"
});
console.log(result);
// { value: "1000" }
with preformats we could simplify the code to
const { result } = await koin.balanceOf("19T7nHRLK9iAUVjPkbsenfUzvbCdpBnARy");
console.log(result);
// 1000
This is very useful because with protobuffers all messages are defined by JSONs, which is not always needed. Then, this feature can be used to simplify the code and make it more readable.
Another design pattern taken from Ethers.js is the "wait" function. As you know, when you submit a transaction it goes to the mempool, and will be there for several seconds until it is mined.
From client's perspective, when a transaction is submitted a "wait" function is returned. Then the client can call this function in order to wait for the transaction to be included in the blockchain. This function waits 10 seconds, and after that it enters in a loop, where it tries to get block id that contains that transaction every second.
Here is a complete example to get balance, mana, and make a transfer.
import { Signer, Contract, Provider, utils } from "koilib";
const provider = new Provider(["https://api.koinos.io:8080"]);
const privKeyWif = "5HzP7VXcKyzqQu2h42uENEjQMDfNuUk6jLQ57t8rfwNadtxzyqZ";
const signer = Signer.fromWif(privKeyWif);
signer.provider = provider;
const koinContract = new Contract({
id: "19JntSm8pSNETT9aHTwAUHC5RMoaSmgZPJ",
abi: utils.Krc20Abi,
signer,
});
const koin = koinContract.functions;
const myAddress = signer.getAddress();
const receiver = "1BqtgWBcqm9cSZ97avLGZGJdgso7wx6pCA";
// 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: myAddress,
to: input.to,
value: utils.parseUnits(input.value, 8),
});
(async () => {
// read the balance of sender
bal1 = await koin.balanceOf(myAddress);
console.log(bal1);
console.log(`Balance of ${myAddress} is ${bal1.result} tKoin`);
// read the balance of receiver
bal2 = await koin.balanceOf(receiver);
console.log(bal2);
console.log(`Balance of ${receiver} is ${bal2.result} tKoin`);
// get mana
resMana1 = await provider.getAccountRc(myAddress);
console.log(`Current mana of ${myAddress} is ${resMana1}`);
// transfer tKoin
resTransfer = await koin.transfer({
to: receiver,
value: "0.00000001",
});
console.log(resTransfer);
txId = resTransfer.transaction.id;
console.log("Transfer submitted to the mempool");
console.log(`Transaction Id: ${txId}`);
console.log("Now waiting to be mined...");
// waiting to be mined
blockId = await resTransfer.transactionResponse.wait();
console.log(`Transaction mined in blockId ${blockId}`);
// get block with the transaction
resBlocks = await provider.getBlocksById([blockId]);
console.log(resBlocks);
blockHeight = resBlocks.block_items[0].block_height;
console.log(`Block number ${blockHeight}`)
// get new mana
resMana2 = await provider.getAccountRc(myAddress);
console.log(`New mana of ${myAddress} is ${resMana2}`);
// check new balance of sender
bal3 = await koin.balanceOf(myAddress);
console.log(bal3);
console.log(`New balance of ${myAddress} is ${bal3.result} tKoin`);
// check new balance of receiver
bal4 = await koin.balanceOf(receiver);
console.log(bal4);
console.log(`New balance of ${receiver} is ${bal4.result} tKoin`);
})();
In the previous sections I focused in the contract for the main token KOIN, how to transfer and get balance. However, it's important to note that this library can be used for any contract in the blockchain. You just have to define the ABI and add it in the constructor of the Contract Class.
For the ABI you need the .proto file and the library protobufjs. Also take into account that this ABI is not the same ABI used in koinos-cli. In particular, descriptors use different format (koilib using json format, cli using binary format). One of the tasks for future releases would be to research the possibility of using a single ABI format for both tools.
To learn more about Koilib V2 go to NPM and check the documentation https://www.npmjs.com/package/koilib