DropJS - Dropil Chain JavaScript Library

An open source JavaScript library for use with Dropil Chain and supported Cosmos-SDK based chains.

The DropJS library offers the ability to create wallets, create transactions, sign transactions offline, and broadcast transactions to a desired LCD URL for any supported Cosmos-SDK based chain.

Installation

NPM

npm install @dropilcoin/dropjs

Yarn

yarn add @dropilcoin/dropjs

Import

NodeJS

Import dropjs in NodeJS by placing the following line at the top of your JS file.

const dropjs = require("@dropilcoin/dropjs")

Browser

Import dropjs into a web page by placing the following JS script in the <head> of your document.

<script src='..path to drop.js'></script>

Using DropJS - Basic Use

Before starting, ensure you have imported the dropjs library (see above).

If you are unfamiliar with any of the terminology or about how Dropil Chain functions in general, refer to the Dropil Chain Documentation

Create a `Drop` instance

Create a new Drop instance by calling the start function of dropjs. The drop variable will be referred to throughout this documentation. Pass in a params object with valid parameters as outlined below.

const dropjs = require("@dropilcoin/dropjs")

let startParams = {
  chainId: 'Dropil-Chain-Poseidon', // String
  lcdUrl: 'https://testnet-api.dropilchain.com', // String
  hdPath: "m/44'/495'/0'/0/0", // String
  bech32Prefix: 'drop', // String
  denom: 'udrop', // String
  powerReduction: 1000000, // int
  baseFee: '10000', // String
  baseGas: '200000', // String
}

let drop = dropjs.start(startParams)

Generate Mnemonic Phrase

Create a new mnemonic phrase by calling the generateMnemonic function of dropjs.

const dropjs = require("@dropilcoin/dropjs");
let wallet = dropjs.generateMnemonic()

Returns a 24-word mnemonic phrase as a String.

Create New Wallet

Create a new wallet using the initialized bech32Prefix by calling the async generateWallet function.

const dropjs = require("@dropilcoin/dropjs")
let drop = dropjs.start(startParams)
let wallet = await drop.generateWallet()

Returns:

{
  "address": "String",
  "mnemonic": "String"
}

::: warning The remaining examples in these docs will not import dropjs or call the start method of dropjs. :::

Get Balance of Address

Call the async getAvailableBalance function to retrieve the available balance of an address. By default, this function returns a denom (i.e. udrop or uatom) value. Pass an optional second parameter of true to return the value represented in the coin value instead of the denom value.

// example balance of drop1qs6a7ht3t2784dn9ee89nv262726v56hks3k5u is 123456789 udrop and the powerReduction of DROP is 1000000

// returns '123456789' udrop
let balanceUdrop = await drop.getAvailableBalance('drop1qs6a7ht3t2784dn9ee89nv262726v56hks3k5u')

// returns '123.456789' DROP
let balanceDrop = await drop.getAvailableBalance('drop1qs6a7ht3t2784dn9ee89nv262726v56hks3k5u', true)

Transactions

This section will outline how to send transactions using DropJS. The current supported transaction types are send, delegate, undelegate, redelegate, withdrawRewards, and modifyWithdrawAddress, submitProposal, vote.

The Params Object

All transactions accept a single argument that is the params object. Each transaction requires different parameters in addition to many optional parameters. The params object is used to make each of the transactions as dynamic as possible for the end user.

Here is a model of the params object with all the potential parameters in a given transaction.

const PARAMS_MODEL = {
  // required for all transactions
  mnemonic: 'String',

  // required for send transaction
  destination: 'String',

  // required for delegate and undelegate transactions
  validatorAddress: 'String',

  // required for redelegate transaction
  validatorSourceAddress: 'String',
  validatorDestAddress: 'String',

  // required for modifyWithdrawAddress transaction
  withdrawAddress: 'String',

  // required for send, delegate, undelegate, and redelegate transactions
  amount: 'String || Number',
  
  // ==== optional parameters below ====

  // adds a memo to any transaction  
  memo: 'String', // default: ''

  // sets the account number and sequence for the transaction; transactions must be 
  // submitted to the network in order by sequence; by default, these are obtained via 
  // the /auth/accounts/{address} API endpoint before signing each transaction
  // **special note: if one is provided, BOTH accountNumber and sequence must be provided 
  // together, not just one
  accountNumber: 'String || Number',  
  sequence: 'String || Number',

  // dictates whether transaction gets broadcasted or returns signedTx instead for later use  
  broadcast: 'Boolean', // default: true

  // sets a custom fee in `udrop` on the transaction
  fee: 'String || Number', // default: 1000000 (1 DROP)

  // sets custom gas limit on transaction
  gas: 'String || Number', // default: 200000
  
  // sets the mode of the transaction when broadcasted; possible values are 'block' which 
  // waits until the transaction is included in a block, 'sync' which waits for the response 
  // from the node, 'async' which returns immediately without waiting for a response
  mode: 'String' // default: 'sync'
}

Send Drops

DropJS makes sending a DROP transaction easy. The send function creates a new send transaction, signs it offline using a provided mnemonic and then broadcasts it to the LCD API URL. Sensitive information is not revealed in this process.

// the following mnemonic was generated for the purpose of this example and does not contain a balance
let mnemonic = 'exit cross gate coconut knee border dial hat upset empower draft glide maple rain erode polar pyramid ketchup seat bone excess fault once length'

// the following example will send 1000000 udrop (1 DROP) from the provided mnemonic to the address shown

let params = {
  mnemonic,
  destination: 'drop1qs6a7ht3t2784dn9ee89nv262726v56hks3k5u',
  amount: 1000000
}

let response = await drop.send(params)