coreum-js

coreum-js

Warning: This library is still in development and it is not production ready.

A JavaScript/TypeScript library for interacting with the Coreum Blockchain

This is the recommended library for integrating a JavaScript/TypeScript app with the Coreum Blockchain, especially for the use of the modules assetft, assetnft, and more. It supports integration with the most popular Browser-Extension wallets; like Keplr, Cosmostation and Leap.

Warning IF YOU DECIDE TO USE A MNEMONIC SIGNER, FOR BETTER SECURITY USE ONLY ON THE SERVER-SIDE.

Contents

1. Features
2. Installation
3. Query Clients
4. Transaction Modules
5. Usage - General
6. Usage - Query balances
7. Usage - Submit Transaction
8. Usage - Event Subscription

Features

1. Query the Coreum Blockchain with ease, using the QueryClients.
2. Sign and broadcast transactions to the Coreum Blockchain using Transaction Modules
3. Subscribe to events that happen on the Coreum Blockchain
4. Connect using the most popular Browser-Extension wallets (Keplr, Cosmostation, Leap)

Installation

Installing coreum-js

npm i coreum-js

Query Clients

coreum-js comes with out-of-the-box modules to query the Coreum Blockchain.

• Auth
• Bank
• Coreum Asset-FT
• Coreum Asset-NFT
• Distribution
• Feegrant
• Gov
• IBC
• Mint
• NFTBeta
• Staking
• TX
• WASM

Transaction Modules

coreum-js comes with out-of-the-box modules to create transaction messages compatible with the Cosmos-SDK and Coreum Blockchain.

• Authz vesting - Vesting itself
• Authz- Authorization for accounts to perform actions on behalf of other accounts.
• Bank - Token transfer functionalities.
• Coreum Asset-FT - Token issuance and management functionalities.
• Coreum Asset-NFT - Non-Fungible Tokens minting and management functionalities.
• CosmWasm - Smart Contracts functionalities.
• IBC - IBC functionalities
• Distribution - Fee distribution, and staking token provision distribution.
• Feegrant - Grant fee allowances for executing transactions.
• Staking - Proof-of-Stake layer for public blockchains.

General

import { Client } from "coreum-js";

// Choose the network to connect. The library will use default nodes for this.
const network = "mainnet" | "testnet" | "devnet";

const coreum: Client = new Client({ network: network });

const connectOptions = {
  withWS: true | false, // optional
};
// connect() will only connect for querying purposes, it won't sign any transaction.
// In order to sign transactions, you need to connect with connectWithExtension or with connectWithMnemonic,
// If choose connectWithMnemonic, DO NOT USE ON CLIENT SIDE.
await coreum.connect(connectOptions); // connectWithExtension || connectWithMnemonic
// If withWS is true, the client will also create and connect to the Coreum Websocket.

// Client exposes different QueryClients to query the Coreum Blockchain with ease.
const {
  ft,
  nft,
  staking,
  distribution,
  mint,
  auth,
  bank,
  ibc,
  gov,
  feegrant,
  nftbeta,
  tx,
  wasm,
} = coreum.queryClients;

// Documentation for each query client can be found here
// https://docs.coreum.dev/api/api.html

// You can get the TX Fee for any transactions with getTxFee
const msgs: readonly EncodeObject[];
const txFee = await coreum.getTxFee(msgs);

// Sign and broadcast the Transaction
const response = await coreum.sendTx(msgs);

// Subscribe to Blockchain events
const subscription = await coreum.subscribeToEvent($EVENT);

// Event
subscription.events.on($EVENT, ({ events, data }) => {
  console.log("EVENT HAPPENED");
});

// Close the subscription
subscription.unsubscribe();

// Coreum + Cosmos Registry. coreum-js uses it internally, but it exposes it in case you have other uses for it
const registry = Client.getRegistry();

Query Balances

// We take the bank query client from the coreum instance.
const { bank } = coreum.queryClients;

const address = "core1ll9gdh5ur6gyv6swgshcm4zkkw4ttakt4ukjma";

const balances = await bank.allBalances(address);

Submit a Transaction

// We take the Bank Transaction Module from the Library.
// Note: This TX module and the Query module are different thing. Query Module is ONLY for queries, not transaction handling
import { Bank } from "coreum-js";
// The Bank module, as any of the other TX modules, offer a quick way to create a msg to be signed and submitted to the blockchain.

// We are creating a MsgSend to transfer coins from one account to another
const send_message = Bank.Send({
  // Address of the sender
  fromAddress: $SENDER_ADDRESS,
  // Address of the receiver
  toAddress: $RECEIVER_ADDRESS,
  // An array of balances to transfer { denom: "subunit of the token", amount: "amount of the subunit to transfer" }
  amount: [
    {
      denom: "ucore",
      amount: "1000000",
    },
  ],
});

// We submit the message by passing it inside the array argument of the sendTx method of the coreum instance.
// This allows to submit multiple message on one single transaction.
const response = await coreum.sendTx([send_message]);

Subscribe to an Event

// The event is the typeUrl of the desired Msg to track.
// You can read more about Event subscription here.
// https://docs.cosmos.network/v0.46/core/events.html#examples
const event = "message.action='/coreum.assetft.v1.MsgMint'";

// Start subscription
const subscription = await coreum.subscribeToEvent(event);

// The event used to subcribe, would be the same one to listen to when it happens.
subscription.events.on(event, (eventData) => {
  // data can be of any type and any shape. Each Event has its unique form.
  // events are the events on the blockchain triggered by the transaction
  const { data, events } = eventData;
});

// Unsubscribe from the event
subscription.unsubscribe();