DeFiner HODLer SDK

Definer Hodler market programmer’s guide

This is a programmer’s guide that explains how to get DeFiner Hodler market data as well as perform transactions, such as deposit, borrow, withdraw etc.

Introduction

This guide is designed to help developers get a HODLer Market data and perform transactions on a HODLer market. The guide is organized as follows:

1. Architectural overview

2. Setting up environment for either

   • NodeJS

   • Pure Javascript

3. Reading data using MarketDataObject

   • Functions and sample code to retrieve each element

4. Transacting using MarketTransactObject

   • Functions and sample code to perform transactions.

Architectural overview

DeFiner HODLer markets are smart contracts deployed on blockchains. A blockchain can be accessed through a URL. Blockchains generally offer both public and private URLs. Public URLs are usually free with no service guarantee while private URLs come for a fee with some level of service guarantee.

Each DeFiner HODLer market can be uniquely identified by the chain it’s on, the address of the smart contracts and a market ID. Market ID is a sequential number generated at the time the market is created and assigned to that market. The SDK abstracts away the addresses of the smart contracts, so to get data or perform transactions only the chain, market ID, and an object of the web3.

For getting data no account or authentication is required. For performing transactions you are required to use a wallet. While any type of wallet may work, only the following have been tested and proven to work:

1. Metamask

This is the end of the architectural overview. The next section describes how to setup the environment

Setting up environment

You can retrieve data or perform transactions by using either NodeJS or pure JavaScript. This section describes how to set up the environment for both.

NodeJS

For NodeJS you need to install nodejs, npm and the definer-hodler npm package as follows:

• Install nodejs. Download and install NodeJS from here.

• Install npm. Download and install npm from here.

• Install the definer-hodler.js npm package by running the following command:\

npm install definer-holder

Pure Javascript

For pure JavaScript you need to download the DeFiner SDK.

• Download the DeFiner SDK from here and make it part of your website.

This is the end of the section on how to set up the environment. The next section describes how to retrieve data.

Reading data using MarketDataReader Object

This section describes how to retrieve data for a HODLer market.

To get data you need to instantiate the MarketDataReader object

Instantiate MarkeDataReader object

The SDK exposes a factory class MarketDataReaderFactory with a static method: getNewInstance to create a MarketDataReader object. The MarketDataReader object provides methods to get the desired data elements of a market as specified in the next section.

The static method: MarketDataReaderFactory.getNewInstance takes three parameters: 1) chain, 2) marketID, 3) web3Obj.

Parameter	Type	Required / Optional	Description
chain	Object	Required	Defines the blockchain for the HODLer Market.
marketId	Number	Required	ID of the HODLer market.
web3Ojb	Object	Required	Object of the main class: Web3 of the Web3.js library.

Chains parameter

The chains parameter defines the chain you will be interacting with. Currently supported chains are listed in Table 1. The Chains parameter is required.

	CHAINS property
Ethereum mainnet	CHAINS.ETH
BNB mainent	CHAINS.BNB
OKC mainnet	CHAINS.OKC
Polygon mainnet	CHAINS.POLY

MarketID parameter

Each Hodler market is assigned a unique ID per chain, (i.e. the same ID will be present in each of the chains.) You will need to supply the marketID for which you need to retrieve data. marketID parameter is required. If you do not know the marketID you can discover it through the UI.

web3Obj parameter

This is the instance of web3 that is created using a provider.

Sample Code

For node.js:

import { MarketDataReaderFactory, CHAINS } from "definer-hodler.js";

const readerObj = await MarketDataReaderFactory.getNewInstance(CHAINS.BNB, 2, web3Obj);

For pure javascript:

<script src="https://domain-name.com/definer-hodler.min.js"></script>

const readerObj = await definerHodler.MarketDataReaderFactory.getNewInstance(
        definerHodler.CHAINS.BNB,
        2,
       web3Obj
      );

Methods to retrieve market data points.

getMarketBaseTokenStakingAPR

This method returns the market base token’s staking APR.

Sample code:

const stakingAPR = readerObj.getMarketBaseTokenStakingAPR();

getMarketBaseTokenDepositMiningAPR

This method returns the market base token’s deposit mining APR.

Sample code:

const depositMiningAPR = readerObj.getMarketBaseTokenDepositMiningAPR();

getMarketBaseTokenTotalDeposit

This method returns the market base token’s total deposit. The returned amount is expressed in the smallest denomination of the market’s base token.

Sample code:

const totalDeposit = readerObj.getMarketBaseTokenTotalDeposit()

getMarketBaseTokenTotalLoan

This method returns the market base token’s total loan. The returned amount is expressed in the smallest denomination of the market’s base token.

Sample code:

const totalLoan = readerObj.getMarketBaseTokenTotalLoan();

getMarketBaseTokenBorrowAPR

This method returns the market base token’s borrow APR.

Sample code:

const borrowAPR = readerObj.getMarketBaseTokenBorrowAPR();

getMarketBaseTokenBorrowMiningAPR

This method returns the market base token’s borrow mining APR.

Sample code:

const borrowMiningAPR = readerObj.getMarketBaseTokenBorrowMiningAPR();

getMarketTokenStakingAPR

This method returns the staking APR of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const stakingAPR = readerObj.getMarketTokenStakingAPR("MARKET_TOKEN_ADDRESS");

getMarketTokenDepositMiningAPR

This method returns the deposit mining APR of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const depositMiningAPR = readerObj.getMarketTokenDepositMiningAPR("MARKET_TOKEN_ADDRESS");

getMarketTokenTotalDeposit

This method returns the total deposit of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const totalDeposit = readerObj.getMarketTokenTotalDeposit("MARKET_TOKEN_ADDRESS");

getMarketTokenTotalLoan

This method returns the total loan of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const totalLoan = readerObj.getMarketTokenTotalLoan("MARKET_TOKEN_ADDRESS");

getMarketTokenBorrowAPR

This method returns the borrow mining APR of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const totalLoan = readerObj.getMarketTokenBorrowAPR("MARKET_TOKEN_ADDRESS");

getMarketTokenBorrowMiningAPR

This method returns the borrow mining APR of a market token.

• Parameter:

  tokenAddress: The address of a market’s token.

• Sample code:

const totalLoan = readerObj.getMarketTokenBorrowMiningAPR("MARKET_TOKEN_ADDRESS");

Perform transactions

This section describes how to transact on a HODLer market. Only the following transactions are available, however the claim related transactions are not available as part of this SDK.

• deposit

• withdraw

• withdrawAll

• borrow

• repay

• setCollateral

To be able to transact on a HODLer market, you need an instance of the class: MarketTransactionManager. The object uses the web3.js library to integrate with the blockchain. The static method of the factory class expects an instance of the main class Web3 that is part of the web3.js library (this is covered in more detail in a later section).

Instantiate MarketTransactionManager object

The SDK exposes a factory class MarketTransManagerFactory with a static method: getNewInstance to create a MarketTransactionManager object. The MarketTransactionManager object provides methods to perform transactions specified in the next section.

The static method: MarketTransManagerFactory.getNewInstance takes three parameters: 1) chain, 2) marketID, 3) web3Ojb.

The following are the constructor’s parameters:

Parameter	Type	Required / Optional	Description
chain	Object	Required	Defines the blockchain for the HODLer Market.
marketId	Number	Required	ID of the HODLer market.
web3Ojb	Object	Required	Object of the main class: Web3 of the Web3.js library.

Chains parameter

The chain parameter defines the chain you will be interacting with. Currently supported chains are listed in Table 1. The Chains parameter is required.

Block chain	CHAINS property
Ethereum mainnet	CHAINS.ETH
BNB mainent	CHAINS.BNB
OKC mainnet	CHAINS.OKC
Polygon mainnet	CHAINS.POLY

MarketID parameter

This is the ID of the market that you would like to transact on. As previously mentioned if you do not know the marketID you can discover it through the UI.

web3Ojb parameter

This is the instance of web3 that is created using a provider which must have an account.

Sample code for Node.js implementation:

import { MarketTransManagerFactory, CHAINS } from "definer-hodler.js";
const transManager = await MarketTransManagerFactory.getNewInstance(
        definerHodler.CHAINS.BNB,
        2,
       web3Obj
      );

Sample code for Pure javascript implementation:

<script src="https://domain-name.com/definer-hodler.min.js"></script>

const transManager= await definerHodler.MarketTransManagerFactory.getNewInstance(
        definerHodler.CHAINS.BNB,
        2,
       web3Obj
      );

MarketTransactionManager methods for transacting on a HODLer market

This section covers all the methods available on the MarketTransactionManager object to transact on a HODLer market. The web3instance provide to the constructor for MarketTransactionManager object creation is expected to have a provider with an account. This account would be referenced in the transaction to be submitted.

Each one of the methods listed below returns a promise events, see here for more details. This allows the caller to respond to the different events emitted as a transaction is getting processed.

deposit

This method handles the “deposit” transaction.

• Parameters:

  • tokenAddress: The address of the token to be deposited. Only the tokens supported on the HODLer market are expected.

  • Amount: The amount of tokens to be deposited. This amount must not exceed the wallet’s balance of the given token (tokenAddress parameter). It is expected to be provided in the smallest denomination of the token to be deposited. Example: 1Eth is expected as 1000000000000000000

• Sample code:

transManager.desposit(3, "0x770f030fdbf63ebf1c939de8bcff8943c2c2d454");

withdraw

This method handles the “withdraw” transaction.

• Parameters:

  • tokenAddress: The address of the token to be withdrawn. Only the tokens supported on the HODLer market are expected. The account must have a deposit balance of the token.

  • Amount: The amount of tokens to be withdrawn. This amount must not exceed the account’s total deposit of the given token (tokenAddress parameter). It is expected to be provided in the smallest denomination of the token to be deposited. Example: 1Eth is expected as 1000000000000000000

• Sample code:

transManager.withdraw(3, "0x770f030fdbf63ebf1c939de8bcff8943c2c2d454");

withdawAll

This method handles the “withdrawAll” transaction.

• Parameters:

  • tokenAddress: The address of the token to be all withdrawn. Only the tokens supported on the HODLer market are expected. The account must have a deposit balance of the token.

• Sample code:

transManager.withdrawAll("0x770f030fdbf63ebf1c939de8bcff8943c2c2d454");

borrow

This method handles the “borrow” transaction.

• Parameters:

  • tokenAddress: The address of the token to be withdrawn. Only the tokens supported on the HODLer market are expected. The account must have the required collateral.

  • Amount: The amount of tokens to be withdrawn. This amount must not exceed the account’s borrowing power. It is expected to be provided in the smallest denomination of the token to be deposited. Example: 1Eth is expected as 1000000000000000000

• Sample code:

transManager.borrow(3, "0x770f030fdbf63ebf1c939de8bcff8943c2c2d454");

repay

This method handles the "repay" transaction.

• Parameters:

  • tokenAddress: The address of the token to be repaid. Only the tokens supported on the HODLer market are expected. The account must have a loan balance of the token.

  • Amount: The amount of tokens to be repaid. This amount must not exceed the account’s total loan of the given token (tokenAddress parameter). It is expected to be provided in the smallest denomination of the token to be deposited. Example: 1Eth is expected as 1000000000000000000

• Sample code:

transManager.repay(3, "0x770f030fdbf63ebf1c939de8bcff8943c2c2d454");

setCollateral

This method handles the enabling or disabling of a deposited token as collateral.

• Parameters:

  • tokenAddress: The address of the desposited token that needs to be enabled or disabled as collateral.

  • enable: A boolean value for enabling or disabling the deposited token as collateral.

• Sample code:

  Enabling a deposited token as collateral.

transManager.setCollateral("0x770f030fdbf63ebf1c939de8bcff8943c2c2d454", true);

Disabling a deposited token as collateral

transManager.setCollateral("0x770f030fdbf63ebf1c939de8bcff8943c2c2d454", false);

Application errors and exceptions

For most of the methods listed above there are internal validations that are executed prior to any interaction with the blockchain. When those validations fail, comprehensive error messages are returned. The following is the list of those error messages.

The errors thrown are object with the following structure:

{ code: ERROR_CODE, msg: ERROR_MESSAGE }

ERROR_CODE	ERROR_MESSAGE
ERR_TK01	The token is not supported
ERR_TK02	The token is not enabled
ERR_TK03	The maturity has not been reached
ERR_SC01	Smart Contra is paused
ERR_ACC01	The account does not have enough deposit
ERR_ACC02	Borrow amount exceeds the account borrow power
ERR_ACC03	The account does not have enough collateral
ERR_ACC04	The account does not have deposit
ERR_ACC05	The account does not have outstanding loans
ERR_TRS01	The amount provided is zero.

All RPC related errors encountered when a transaction is submitted must be handled by the consumer of the SDK. Examples of code for parsing RPC errors can be found on the internet.