Nodejs

Build applications on top of the Xend Finance smart contracts.

Installation

Using npm:

npm install @xend-finance/web-sdk

Using yarn:

yarn add @xend-finance/web-sdk

Xend Finance has different saving strategies that help you save your money in stable currencies;

• Personal Savings

• Esusu

• Cooperative Savings

You can make use of one or all of these strategies

Example

require('dotenv').config(); // this helps you read from your env file

import XF from '@xend-finance/web-sdk'; // using the import format
//// OR ////
const { default: XF } = require('@xend-finance/web-sdk'); // using the require module


const chainId = 56; // Binance Smart Chain Mainnet
const privateKey = process.env.PRIVATE_KEY; // saved in your env file


const setup = async () => {
  const instance = await XF(chainId, privateKey, { env:"mainnet" });
  return instance;
}

const makeDeposit = async () => {
  const { Personal } = await setup();

  const depositAmount = "100";
  const response = await Personal.flexibleDeposit(depositAmount);
  return response;
}

What you need to setup SDK

1. Chain ID

The SDK has support for the chain id's below

• 1 - Ethereum Mainnet

• 56 - Binance Smart Chain Mainnet

• 97 - Binance Smart Chain Testnet

• 0 - Local Instance of Ganache

2. Private Key

The SDK needs the private key of your blockchain wallet to help you sign and send transactions when you call different methods of the SDK. You can get this from your wallet, like Metamask by opening Account Details and exporting your private key.

Please note this is supposed to be a secret. It is advised you put it in an environment file that you don't make public anywhere.

Account details on Metamask

Export Private Key

3. Options

This is the third requirement for setting up the SDK. It is optional and if no options argument is passed in for initializing the SDK, the testnet environment is used. This option is an object with 3 properties, env, protocols and protocolName.

Properties	Values	Description
env	local, testnet, mainnet	Required
protocols	Array of protocols objects	This can only be used when the env is local.
protocolName		Used in the case of multiple protocols available. This is optional if you don't know the protocol available. After setting up the SDK without the protocolName. You can call a method to return the available protocol names.

Note: whenever you use the options argument you have to provide value for the env property even if it is "testnet".

Scenario

You can use Xend Finance in as many scenario's you can come up with, but there are 2 examples

1. Use one general address for all your transactions (like a custodial wallet)

2. Create a new address for each of your users and use it for their transactions

Protocol Type

This is the structure of a protocol to be used by the SDK and will be helpful when using the SDK on your local machine with an instance of tools like ganache. Below is a structure with venus lending protocol.

{
  "name":"Venus",
  "code":"venus",
  "addresses": {
    "PROTOCOL_ADAPTER": "0x655ca90baa0936A056eFC5E389Baf97026DfFdA3",
    "PROTOCOL_SERVICE": "0xd99d68d7d01Af99F3089d0EFBB12C1A02658d436",
    "GROUPS": "0x41E95e88c0dCEaCe4159f4118217B67038aaE6F0",
    "CYCLES": "0x0884d96d51dDF544865af8eE3fF5a354e815CC32",
    "ESUSU_SERVICE": "0x5a32A13770Db90Da7DEA78005Ce110BBBdA8Aac3",
    "ESUSU_STORAGE": "0x2603ba3426aA62d708dbEcf138E04B91e1548A74",
    "ESUSU_ADAPTER": "0xC1C39c7086D1FAFA8a2ffd49d0eA5ECBD37Bf3d1",
    "COOPERATIVE": "0x52e343f0E797717195df7858CE8A1080504c4B6d",
    "PERSONAL": "0x1349236eFfA145CbE2Ad80A20fFee192e35131fa",
    "CLIENT_RECORD": "0x715Adf500E2a5d2a823eec12c9e34b6093Ea7272",
    "XEND_TOKEN": "0x4a080377f83D669D7bB83B3184a8A5E61B500608",
    "TOKEN": "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56",
    "PROTOCOL_CURRENCY": "VBUSD"
  }
}

Setting up a development environment

The setup example above works right off the bat with real funds. So you will have to have BNB for gas fees and BUSD for the actual savings on Xend Finance, but for testing purposes, we won't be using real funds.

Step 1

The tool we need to set up this development environment is Ganache. Straight from Ganache's website

Ganache is a personal blockchain for rapid Ethereum and Corda distributed application development. You can use Ganache across the entire development cycle; enabling you to develop, deploy, and test your dApps in a safe and deterministic environment

With Ganache we have a copy of a blockchain running locally on our machine.

Assuming you already have NodeJS installed on your machine, you can install Ganache globally with npm, which makes it accessible from anywhere on your computer's terminal.

npm i -g ganache-cli

Running the ganache-cli starts a local blockchain on your machine. It will be similar to the screenshot below.

Run ganache-cli

At the end of the output after running ganache-cli you should see the Listening on 127.0.0.1:8545 which is your localhost port 8545. This is an indication you have Ganache CLI installed correctly. You can stop it by typing Ctrl + C on your terminal.

Step 2

Moving on with setting up our local environment, we would be making use of a powerful feature that Ganache has, which is the option to start Ganache with a fork of a blockchain. What this means is that you can start Ganache as if it is the current state of the Ethereum Mainnet or Binance Smart Chain running locally on your machine.

ganache-cli --fork https://bsc-dataseed.binance.org/

Running the code above would make your machine to be running the current state of the Binance Smart Chain. That's cool for development.

To us now, why this is important is because Xend Finance Smart Contracts are already deployed and running on the Binance Smart Chain. So you can immediately start using functions in the Xend Finance Smart Contracts for your own applications in this local test environment we have set up with Ganache.

Step 3

The final thing we need for this setup to be complete is to make sure we have BUSD which is used for savings and BNB which is used for paying gas fees.

So if you currently own an account that has BNB and BUSD on Binance Smart Chain, when you run Ganache CLI with the fork of the Binance Smart Chain like we did above, that your account will still have the funds available to you on your local blockchain running on your machine and you can go ahead to start making use of the Xend Finance SDK. You can jump to the next section to make your first deposit. But if you don't have or you prefer not to use your account, there is a way to have both BNB and BUSD in a fresh account.

For getting BNB, that's easy, whenever your run ganache-cli 10 accounts are generated for you with 100 BNB in them. Please note that when you run ganache-cli with the fork of Binance Smart Chain, whenever you see ETH, it represents BNB. Just like the screenshot above on running ganache-cli, we have accounts and their corresponding private keys printed on your terminal and you can choose any one of them for your tests.

We now have BNB from the account we choose from the Ganache output when we run it. But those addresses don't have BUSD, just BNB. So we need to find an account that has lots of BUSD to transfer from it to our own account (that we get from the Ganache output).

Remember at the time of running ganache with the fork of the Binance Smart Chain, we have the current state of the blockchain at that time and there are addresses that have lots of BUSD in them, so we need to get one of those addresses and use it to run our ganache-cli fork again so that we can be able to locally transfer BUSD from that account that has lots of BUSD to your own account, which is one of those you choose from the Ganache output when we run Ganache.

We can find that account by going to https://bscscan.com/ and searching for BUSD in the search bar and clicking on the Holders tab. We are interested in addresses in the Holders table that don't have the paper icon beside it, which indicates that those addresses are not smart contract addresses.

Select BUSD from list

Interested in non-contract addresses that have BNB also

You can confirm that the account has BUSD and BNB also by copying the address and pasting the address in the search bar on the bscscan.com website to see the funds available in the account. If it has both BNB and BUSD, then we a good to go.

Selected address

So we can start Ganache by running the fork of the Binance Smart Chain and unlock that address we just got to enable us to send BUSD from that address.

ganache-cli --fork https://bsc-dataseed.binance.org/ --unlock 0xd6faf697504075a358524996b132b532cc5D0F14

Transfer Funds & Make Your First Deposit and Withdrawal

You can quickly pull this repository and go through the README file. The code has already been set up for you, you will just need to create an env file and add the PRIVATE_KEY you get from ganache-cli output. The scripts in the repository will transfer funds from the unlocked address to your own address, and you can begin to call functions from the SDK.

// Example Script to send BUSD
const web3 = require('web3')
const busdAbi = require('./busd-abi.json')

const w3 = new web3("http://localhost:8545")
const busdAddress = "0xe9e7cea3dedca5984780bafc599bd69add087d56"
const busd = new w3.eth.Contract(busdAbi, busdAddress);

const receiver = "0x.....";
const unlockedAddress = "0xd6faf697504075a358524996b132b532cc5D0F14";

const sendFunds = async () => {
		const amountToFund = 1000;
		const amount = BigInt(amountToFund) * BigInt(Math.pow(10, 18))
		await busd.methods.transfer(receiver, amount).send({ from: unlockedAddress })
		console.log('* sent *\n')
}

sendFunds(); // run the function

If you have questions you can always ask them on the Developers Community on Telegram.

Some available functions

General

Name	Parameters	Description
retrieveWallet()		address of the account used to initialize SDK. Returns an object with the wallet address of the account.
apys()		will only return values if you are on mainnet

Personal Savings

Name	Parameters	Description
flexibleDeposit	depositAmount
fixedDeposit
fixedInfo
flexibleInfo
withdrawFixed	recordId
withdrawFlexible	amount	This should be the amount in share balance and not in the stablecoin like BUSD. You can get the share balance from the returned values in the flexibleInfo function.
walletBalance

Esusu

Name	Parameters	Description
create
walletBalance

Cooperative Savings

Name	Parameters	Description
create
walletBalance