CudosJS - JavaScript Library for the Cudos network
⭐ Developed by Cudos
A JavasSript Open Source Library for Cudos network.
Installation
In order to fully use this library, you need to run a local or remote full node and set up its rest server, which acts as an intermediary between the front-end and the full-node. You can use the cudos-cli.
NPM
npm install cudosjs
Yarn
yarn add cudosjs
Using CudosJS
CudosJS acts as a package that extends the cosmJS library. It builds-up upon it, so that it's tailored to the specifics of the Cudos Network. If you've used cosmJS before, than the API should feel quite familiar to you.
CudosJS usage is organized mainly around using it's two clients - StargateClient
and
SigningStargateClient
.
-
SigningStargateClient
- used to sign and broadcast transactions.
import { SigningStargateClient, DirectSecp256k1HdWallet } from "cudosjs"
// Load an account
const mnemonic = "surround miss nominee dream gap cross assault thank captain prosper drop duty group";
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic);
const [firstAccount] = await wallet.getAccounts();
const rpc = http://localhost:26657
const signingClient = await SigningStargateClient.connectWithSigner(rpc, wallet)
We need an RPC endpoint (that will be used to connect to the network) and a wallet ( used to sign the transactions ). A ready to use SigningStargateClient is created by connecting it to the RPC and the wallet.
// Sending tokens to another cudos address
import { coin, GasPrice } from "cudosjs"
...
const recipient = "cudos1a0kjzmvrkul70nxle63j8day47ve74g00zl66w";
const amount = { // same as const amount = coin("1234567", "acudos)
denom: "acudos",
amount: "1234567",
};
const result = await signingClient.sendTokens(firstAccount.address, recipient, [amount], "Have fun with your cudos coins");
assertIsBroadcastTxSuccess(result);
...
// Sending a message to the NFT module
const gasPrice = GasPrice.fromString('1acudos');
const correctToken = {
approvedAddresses: [],
id: '1',
owner: '',
name: 'testToken',
uri: 'testUir',
data: 'testData',
}
const result = await signingClient.nftMintToken(firstAccount.address, correctDenom.id, correctToken.name, correctToken.uri, correctToken.data, recipient, gasPrice)
assertIsBroadcastTxSuccess(result);
...
// Sending a message to the Gravity module
const gasPrice = GasPrice.fromString('1acudos');
const coinAmount = {denom:"acudos", amount: "1000"}
const feeAmount = {denom:"acudos", amount: "100"}
const ethAddr = "0xa677d7229924af63098b9bb70b041a03a1ec7d8c"
const result = await signingClient.gravitySendToEth(firstAccount.address,ethAddr,coinAmount,feeAmount,gasPrice)
assertIsBroadcastTxSuccess(result);
-
StargateClient
- this one is used to query the Cudos Network. It's quite simple to work with:
import { StargateClient } from "cudosjs"
const rpc = http://localhost:26657
const queryClient = await StargateClient.connect(rpc)
First we need an RPC endpoint, that will be used to connect to the network. Then a StargateClient
is created by connecting it to the network.
** In this example the client is connecting to a local test network, created using cudos-blast.
...
const cudosAddress = "some cudos address"
const height = await queryClient.getHeight() // returns the current height of the blockchain
const isAccount = await queryClient.getAccount(cudosAddress) // check if an account exists
const balance = await queryClient.getBalance(cudosAddress, "acudos") // get the balance of the account in the respective denom
const chainId = await queryClient.getChainId()
...
As shown above - query methods typical to any cosmos-based blockchain are directly available on the StargateClient
The Cudos Network however includes some specific, additional modules - each with it's distinct messages and queries ( such examples are the group, nft and gravity modules). Methods for queries related to those module are grouped in objects inside the StargateClient
, where each object starts with the name of the module (e.g.nftModule
, gravityModule
, groupModule
):
// Querying the Nft Module
...
const correctDenom = {
creator: '',
id: 'testdenom',
name: 'test-denom-name',
symbol: 'test-denom-symbol',
schema: 'test-denom-schema',
}
const correctToken = {
approvedAddresses: [],
id: '1',
owner: '',
name: 'testToken',
uri: 'testUir',
data: 'testData',
}
const getDenom = await queryClient.nftModule.getNftDenom(correctDenom.id) // get a denom by it's ID
const getToken = queryClient.nftModule.getNftToken(correctDenom.id, correctToken.id) // get a token
const isApproved = queryClient.nftModule.nftIsApprovedForAll(cudosAddress, cudosAddress2)
// Querying the Gravity Module
...
const pendingTrxs = await queryClient.gravityModule.getPendingSendToEth(cudosAddress) // check for unbatched transactions for a particular account
Constructing custom Msg's
Most of the times the already provided methods inside SigningStargateClient
would be enough. But sometimes you need to construct and send your messages manually ( for example when simulating a transaction to calculate the Fees). CudosJS provides an utility function generateMsg
to make custom message construction easier:
import { GasPrice, generateMsg, estimateFee } from "cudosjs"
...
// Calculating the Fees for sending a msgSendToEth message.
const bridgeFee = {denom:"acudos", amount: "10000"}
const amount = coin('1000000000000', "acudos")
const memo = "Have fun spending your cudos"
const gasPrice = GasPrice.fromString(`1acudos`)
const simulatedMsg = generateMsg('msgSendToEth', {
sender, // cudos addrs
ethDest: destination, //eth addrs
amount
bridgeFee
})
const approxFee = await estimateFee(client, sender, [simulatedMsg], gasPrice, gasMultiplier, memo)
const result = await client.signAndBroadcast(
sender,
[simulatedMsg],
approxFee,
memo
);
Custom Queries
Using the available methods inside StargateClient
automatically decodes the response. However when constructing and sending queries yourself, you have to decode the responses as well. You can use the decodeQryResponse
method inside StargateClient
:
...
// Executing a custom query using filters
const filteredTx = await queryClient.searchTx({
tags: [{ key: "message.action", value: "/gravity.v1.MsgSendToCosmosClaim" }],
})
// Decoding the result - decodes all messages inside the response
const decodedRes = await qClient.decodeQryResponse(filteredTx)