initia.js

Initia.js is a TypeScript-written JavaScript SDK tailored for the Initia blockchain, enhancing the development experience with user-friendly TypeScript definitions and integration with Initia's core data structures.

Main Features

• Improved TypeScript Definitions: Offers comprehensive integration with Initia core data structures for an enhanced developer experience.
• Core Layer: Includes key management, BCS serialization, and support for initia.proto.
• Client Layer: Facilitates API request generation and REST provider interaction.

Installation

Before installation, check the latest version of npm:

npm install @initia/initia.js

Usage

The usage section of this document provides detailed explanations and code examples of the most commonly used classes of the Initia.js library, which can be utilized both in a Node.js environment and within a browser.

REST client

RESTClient class facilitates interaction with the Initia blockchain.

import { RESTClient } from '@initia/initia.js'

const rest = new RESTClient('https://rest.testnet.initia.xyz', {
  chainId: 'initiation-2',
  gasPrices: '0.15uinit', // default gas prices
  gasAdjustment: '1.75',  // default gas adjustment for fee estimation
})

gasPrices and **gasAdjustment**are optional, but essential for the fee estimation

Key

An abstract key interface that enables transaction signing and provides Bech32 address and public key derivation from a public key.

import { MnemonicKey } from '@initia/initia.js'

const key = new MnemonicKey({
  mnemonic: 'bird upset ...  evil cigar', // (optional) if null, generate a new Mnemonic key
  account: 0, // (optional) BIP44 account number. default = 0
  index: 0, // (optional) BIP44 index number. default = 0
  coinType: 60, // (optional) BIP44 coinType. default = 60
})

BCS

BCS(Binary Canonical Serialization) is the binary encoding for Move resources and other non-module values published on-chain.

import { bcs } from '@initia/initia.js'

// serialize, serialize value to BCS and encode it to base64
const serializedU64 = bcs
  .u64() // type
  .serialize(1234) // value 
  .toBase64()

// deserialize
const deserializedU64 = bcs
  .u64() // type
  .parse(Uint8Array.from(Buffer.from(serializedU64, 'base64')))

// vector
const serializedVector = bcs
  .vector(bcs.u64())
  .serialize([123, 456, 789])
  .toBase64()

// option
const serializedSome = bcs.option(bcs.u64()).serialize(123)
const serializedNone = bcs.option(bcs.u64()).serialize(null)

Support types for BCS

`u8`, `u16`, `u32`, `u64`, `u128`, `u256`, `bool`, `vector`, `address`, `string`, `option`, `fixed_point32`, `fixed_point64`, `decimal128`, `decimal256`

Msg

Msgs are objects whose end-goal is to trigger state-transitions. They are wrapped in transactions, which may contain one or more of them.

• MsgSend()

Send coins to others.

import { MsgSend } from '@initia/initia.js'

const msg = new MsgSend(
  'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu',   // sender address
  'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np',   // recipient address
  '1000uinit',                                     // send amount
)

• MsgDelegate()

Delegate governance coin to validators (staking).

import { MsgDelegate } from '@initia/initia.js'

const msg = new MsgDelegate(
  'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu',             // delegator address
  'initvaloper14qekdkj2nmmwea4ufg9n002a3pud23y8l3ep5z',      // validator's operator (valoper) address
  '100000uinit',                                             // delegate amount
)

• MsgUndelegate()

Undelegate governance coin from validators (unstaking).

import { MsgUndelegate } from '@initia/initia.js'

const msg = new MsgUndelegate(
  'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu',             // delegator address
  'initvaloper14qekdkj2nmmwea4ufg9n002a3pud23y8l3ep5z',      // validator's operator (valoper) address
  '100000uinit',                                             // undelegate amount
)

• MsgExecute()

Execute move contract function.

import { MsgExecute } from '@initia/initia.js'

const msg = new MsgExecute(
  'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu', // sender address
  '0x1',                                         // owner of the module
  'dex',                                         // name of the module
  'swap_script',                                 // function name
  [],                                            // type arguments
  [                                              
    bcs.address().serialize('0x2').toBase64(),   // arguments, BCS-encoded
    bcs.address().serialize('0x3').toBase64(),   // arguments, BCS-encoded
    bcs.u64().serialize(10000).toBase64()        // arguments, BCS-encoded
  ]
)

Tx broadcasting

• createAndSignTx()

Create a wallet and sign transaction.

import { Wallet, RESTClient, MnemonicKey, MsgSend } from '@initia/initia.js'

const key = new MnemonicKey({
  mnemonic: 
    'moral wise tape glance grit gentle movie doll omit you pet soon enter year funny gauge digital supply cereal city ring egg repair coyote',
})

const rest = new RESTClient('https://rest.testnet.initia.xyz', {
  chainId: 'initiation-2',
  gasPrices: '0.15uinit', // default gas prices
  gasAdjustment: '1.75',  // default gas adjustment for fee estimation
})

const wallet = new Wallet(rest, key)

const sendMsg = new MsgSend(
  'init14l3c2vxrdvu6y0sqykppey930s4kufsvt97aeu',   // sender address
  'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np',   // recipient address
  '1000uinit',                                     // send amount
)

const signedTx = await wallet.createAndSignTx({
  msgs: [sendMsg],
  memo: 'sample memo',
})

When sending coins with MsgSend, sender address should be the same as wallet address.

• broadcast()

broadcast() is the action that sends your transaction to the blockchain code.

const broadcastResult = await rest.tx.broadcast(signedTx)

Queries

• balance()

Query the balance of the account.

const balances = await rest.bank.balance('init14l3c2vxrdvu6y0sqykppey930s4kufsvt97aeu')

• viewfunction()

Obtain the return values of a Move view function.

const res = await rest.move.viewFunction(
  '0x1',                                         // owner of the module
  'dex',                                         // name of the module
  'get_swap_simulation',                         // function name
  [],                                            // type arguments
  [       
    bcs.address().serialize('0x2').toBase64(),   // arguments, BCS-encoded
    bcs.address().serialize('0x3').toBase64(),   // arguments, BCS-encoded
    bcs.u64().serialize(10000).toBase64()        // arguments, BCS-encoded
  ]                           
)