Getting Started with the DeFi Terminal Software Development Kit (SDK)

The release of the DeFi Terminal SDK complements our no-code solutions, now providing developers with audited and secure smart contracts to integrate with their decentralized apps

We’re glad to share the DeFi Terminal Software Development Kit (SDK) release today, which allows developers to integrate our liquidity mining and staking smart contracts into their applications. This is our first SDK release, followed by our Bridge and DEX SDKs. You can access our repository here.

In our mission to provide an end-to-end infrastructure for blockchain builders, the release of our SDKs complements our no-code solutions for projects. This makes it easier for developers to integrate liquidity mining and staking into their applications, using audited and secure smart contracts. Now builders can integrate our smart contracts in the backend and build their own experiences on top of them, accelerating their roadmap and development growth.

How an SDK contributes to mass adoption

At AllianceBlock, we continuously discuss the key elements that we need in the industry to increase the adoption and usage of blockchain technology in people’s daily lives. At one of our DeFi Terminal development team meetups (spread over five countries!), we have set the goal to be the industry benchmark in user experience for our solutions and platforms.

This is a bold goal, and we feel confident that we have fulfilled that goal with our user-friendly and approachable design for the DeFi Terminal. We want to give the user a trustful experience in a trustless domain and worked to make a solution that gives users confidence and trust in staking their assets. Why? When you remove the bank and users become responsible for their funds and security in new DeFi platforms, you need to make them feel comfortable managing their transactions and give them the confidence to navigate the application. We often don’t see building a trustful experience as a priority for many platforms, even if the industry has been around for years.

The next step

In parallel with deploying our no-code solutions for liquidity mining, staking, bridging and peer-to-peer funding, we have also developed software development kits (or SDKs). These resources enable developers to use our smart contracts in the backend (in JavaScript) and integrate them with their applications with their front end. We have open-sourced these packages and published them on npm (originally Node Package Manager), a package repository for JavaScript-based projects. Today we have released the SDK for the DeFi Terminal, with the SDK for Bridge and DEX coming next.

These SDKs streamline the various multiplatform journeys users have to go through in the current blockchain and DeFi space. With direct integrations in developers’ apps, we aim to reduce the number of platforms users must connect to, improve user experience and build more confidence and trust in Web3 applications.

What do we mean by this? For example, a user wants to participate in the campaigns of a new project on an EVM-compatible layer 1 network they have recently encountered. The first step is researching the project and determining how to obtain their tokens. The following are the typical steps a new user has to go through:

1. Find a platform that allows one to on-ramp fiat currency to buy crypto (Platform 1);
2. Hop on to another platform to swap their crypto with the network-native token where the project is deployed (Platform 2);
3. Transfer the tokens to MetaMask or another crypto wallet (Platform 3);
4. Connect to another exchange that has the project token to swap the network-native tokens for the project’s token (Platform 4);
5. Visit the project’s website to learn how and where to stake the project tokens (Platform 5) and be led to
6. The staking platform where the users can finally stake the project tokens in the staking campaign.

Reducing the number of platforms users must go through simplifies their journey. An integrated user experience encourages greater adoption by mitigating confusion and space for mistakes. Projects can build confidence and trust in their applications and platforms by ensuring that once their users get to their website, key actions such as staking and participating in campaigns are already integrated.

For users who have just discovered a new project, there are a lot of steps and platforms to go through to participate in a staking campaign. This user journey can introduce a lot of confusion and errors and is not an optimal experience.

The DeFi Terminal SDK (with the upcoming Bridge and DEX SDKs) allows developers to integrate staking and liquidity mining into their applications using our audited and secure smart contracts. Developers can utilize our code in the backend or create their branded campaigns with our white-labeled solution.

Our smart contracts (and solutions) are chain-agnostic (on EVM-compatible networks), so projects can launch their campaigns quickly regardless of the networks they support. This direct integration simplifies users’ experience once they have reached the project website, enabling them to access the projects’ liquidity mining and staking campaigns immediately. An integrated solution makes it easier for users to get started and engage with the project. This builds trust and confidence in using the application, as there are no additional platforms to connect and navigate. For DeFi, this is a big step in the right direction to encourage adoption, making more streamlined, trustful journeys for users.

Benefits for Projects

For new and already established projects, direction integration via the SDK helps keep users on their platform. Like Web2 platforms, keeping users in a single platform and enabling them to perform important actions within a single, streamlined interface makes it more straightforward for users to onboard, helping increase conversion rates.

In parallel, this SDK also helps us develop our own solutions and in attaining one of our key goals — to create a single-platform journey where users can buy, sell, swap, stake, and participate in DeFi using an application and environment they can trust that is designed with the users in mind first.

Encouraging mass adoption

The DeFi Terminal SDK is just the first step in our goal to encourage mass adoption of Web3 technologies. By helping projects create a trustful platform using our smart contracts, users feel more confident participating in the project’s campaigns and engaging in their ecosystem.

The Bridge SDK will enable integration with our Cross-Messaging Protocol to support multi-network applications, making it easy to deploy on multiple chains and allowing seamless switching between them. The DEX SDK will enable integrated swaps in the applications while supporting multiple networks, further removing another step in the journey for users.

Using these SDKs under the hood and developing a trustful experience on the front end enables users to feel more comfortable and confident in using our applications. This is our thesis on how we can encourage mass adoption of DeFi. Each SDK release is a step in bringing AllianceBlock to the position of being the backend for blockchain through our end-to-end infrastructure.

Now that we have discussed the vision for our SDKs, let’s dive in deeper and break the ice by having a developer-focused walkthrough on integrating the DeFi Terminal SDK and using its functionality.

The Tutorial

Creating a new app

The following sections of the article are geared towards developers and will require experience and knowledge of JavaScript and prior knowledge of React or NextJS. We’ve designed the SDK to be approachable even for those unfamiliar or inexperienced in Web3 and blockchain development. Essential Web3 functions are already provided in the SDK, and we explain them through this article’s examples.

With this walkthrough, we aim to build a simple web application using NextJS that will list all Staking (Single-Sided) campaigns of a single (test) project on the Polygon (mainnet) network and be able to stake tokens in it.

For projects that want to launch their liquidity mining or staking campaigns quickly and easily using a no-code solution with no development time, check out our website here.

We will create a new app using:

npx create-next-app

And we will name it defi-app.

Running this command will create the standard files, and we can continue from this to implement the DeFi Terminal SDK. We will then need to install all the packages needed to run the SDK:

npm i @ethersproject/providers @ethersproject/units @allianceblock/lmaas-sdk @web3-react/core @web3-react/injected-connector

This command will install the Web3 packages we need and the DeFi Terminal SDK lmaas-sdk.

The foundation of a Web3 app

Let’s open ./pages/_app.js and prepare our application to be Web3 ready:

The initial lines in the code enable interaction with the MetaMask wallet and set up the SDK’s global use throughout the app. Let’s focus on Line #23, which is relevant to this tutorial:

For the SDK to work, we will need to apply a configuration. This configuration essentially needs two parameters:

• The API endpoint we want to interact with
• The tenant ID of the project we want to interact with

The API endpoint will always remain the same; there is only a difference between development, staging, and production environments, where this endpoint is the production environment.

Each client of the DeFi Terminal has a tenant ID, usually the project’s name, always in lowercase. Developers can also find it in the URL of the project’s DeFi Terminal portal. For example, AllianceBlock’s tenant ID is allianceblock, with our DeFi Terminal portal at https://allianceblock.defiterm.io.

The SDK is integrated on a per-project basis, so we’ll have to provide the tenant ID during initialization. For demonstration purposes, we are using sdkdev for the tenant ID as it already contains a sufficient amount of campaigns to interact with (note that this tenant does not have its DeFi Terminal URL).

With these steps done, the SDK is added to the global state, and we can use it easily in a component for this tutorial.

Implementation of the SDK in a component

In this next part, we will edit the file at ./pages/index.js.

There’s a lot to unpack here, beginning with Line #8:

This method enables easy access to a reference of the SDK and creating a new instance if not done already, assuming the network/chain ID is known or provided when the config is set. This could also be handled on another global level or through a utility class.

We take three arguments for this method:

network: The network ID. This is a standard ID used for EVM-compatible networks. This ID is also used MetaMask configuration. These are the network IDs we support within the DeFi Terminal at the time of writing:

• 1 (Ethereum): "eth"
• 56 (BNB Chain): "bsc"
• 137 (Polygon): "polygon"
• 43114 (Avalanche): "avalanche"
• 246 (Energy Web Chain): "ewc"
• 1284 (Moonbeam): "moonbeam"

provider: We assume this is the provider injected by MetaMask once a wallet is connected.

configWrapper: As previously discussed for ./pages/_app.js.

Then from Lines #19–23, we see the following variables declared:

Per line:

• We are getting the global state to use the SDK
• We are using the Web3 hook, so we can interact with the SDK using MetaMask
• We are preparing a list of campaigns (component state)
• We are setting up a loading indicator while waiting for the campaigns to load (component state)
• We are setting up the network IDs we support (see a bit above)

Test run

Now we have all the foundation done, let’s give the application a spin by running the command:

npm run dev

We should see something like this:

Make sure your network in MetaMask is connected to the Polygon Mainnet network. You can quickly add the Polygon Mainnet network to your MetaMask by using Chainlist.org, connecting your wallet, and searching for Polygon Mainnet.

With the test application connected to the Polygon Mainnet network (or any of our supported networks), we will see the wallet address of the connected test wallet.

The campaigns will begin to load, and after a few seconds, we will see a list of campaigns. With the tenant ID sdkdev , there is only one campaign.

SDK usage explained

Now, let’s go back to the code and break down what we see here, starting from Line #30:

The function responsible for loading the campaigns is wrapped in this useEffect hook and contains functionality for handling the loading state and preparing the data for the campaign overview.

Some things are worth explaining here. Let’s go to Lines #32–34:

To interact with the campaigns on-chain we need to fetch the configuration data of the tenant off-chain. This is to determine which campaigns they have configured and use that data to interact with the blockchain.

Here’s a simple overview of how a web application, through the SDK, can send a request to the API to fetch the configuration data from DeFi Terminal and interact with blockchain to fetch the onchain data for a campaign. This call is then returned to the web application for further processing.

Through the DeFi Terminal SDK, a decentralized application can send a request through the API to fetch tenant data and interact with the blockchain for on-chain data.

Looking back at Line #32, we see the mention of configWrapper. This is what’s responsible for the API request to get the off-chain Liquidity Mining campaign configuration data getLmCampaigns().

Additionally, the configWrapper needs to know which network to look into, which is accepted as a string. A helper function getProtocolByChainId is available to retrieve the value for chainId as set at Line #12.

Line #35 is worth explaining too:

A signer is used to deal with the connected account in relation to the on-chain data. For example, if we want to display data about the campaign, we need to know the connected wallet to determine if the user has staked anything and, if so, by how much. Additionally, the signer is forwarded to the campaign methods that support staking and withdrawing.

Then from Lines #37–39, we see how this data is used to interact with the SDK:

So configWrapper is used to get off-chain data, campaignWrapper is used to get on-chain data for Liquidity Mining campaigns and soloStakerWrapper for single-sided staking campaigns (as used in this example). The getCardDataCommon method is used to fetch the data you would ideally display on a card component for that campaign.

The rest of the code is straightforward, toggling the loading indicator state until all promises are cleared.

Now let’s dive into the displaying of the data in the component from Lines #90–93:

We can identify the following interesting properties:

• The campaign’s smart contract address: campaign.campaign.campaignAddress
• How many tokens are staked: campaign.totalStaked
• The current APY: campaign.apy
• The version of the campaign: campaign.campaign.version (1 is for the initial release smart contracts, 2 are the updated smart contracts, released earlier this year)

Staking

This is where it gets fun! We will go over the staking functionality and go over core functionality.

Let’s update the code with the “approve” and “stake” buttons and handlers. You can take the updated code from this gist:

Let’s first look at the methods that handle this functionality from Lines #62–95:

To understand the methods, we need to understand the flow and order of operations.

In a staking campaign, users stake tokens in a campaign (a smart contract), and they are rewarded with tokens for staking their provided tokens. These tokens are ERC20 tokens that need to be approved if handled from a smart contract. So if we want the campaign’s smart contract to be able to take the tokens from our wallet and stake them, we will need to whitelist the smart contract’s address on the contract of the token by approving the token.

When withdrawing our stake, the smart contract already has all the rights over the tokens it contains, so it doesn’t need another approval to send them (and the rewards) back to us.

To list the order of operations:

• Approve token spending on token contract for staking campaign contract (need Signer object for this — as discussed in the previous section): stakerSdk.soloStakerWrapper.approveToken() method
• Stake the tokens in the contract: stakerSdk.soloStakerWrapper.stake() method

The handling of these functionalities goes through simple button clicks, demonstrated here from Lines #132–141:

We can further optimize this by showing the approve button only when tokens are not approved yet, but we have not done so in this example.

Note that on Line #129 we added a piece of code to show how much was staked so far.

Handling transactions

The approve, stake, and exit methods each mutate something on the blockchain network. Therefore, they execute a transaction that is returned by the method.

This transaction can take a few seconds up to hours, depending on the amount of GWEI used when confirming the transaction in MetaMask and how congested the network is. This is why it is important to inform the user of the status (see Line #24) of the transaction on the front end.

Something like this could be implemented:

The following steps are shown here:

• Toggle the transaction loading indicator (we could display a spinner at this state, for example);
• Execute the transaction;
• Wait for the transaction to complete (in a real-world application, we should also check the status and inform the user if the transaction failed);
• Toggle the transaction loading indicator again (this is where we would hide the spinner again).

A note on the loading indicator/spinner: in our example, we disable the button until the transaction is completed.

Build with our SDK

We invite developers to check out the SDK source here on GitHub to understand its full potential and functionality. We are also working on our developer portal, including additional documentation, which should get into more detail about our functions and hooks.

With this simple walkthrough, we hope developers can start trying out the SDK for your project (or any other integration purpose you thought of!). We welcome submissions of any components, packages, or integrations in business applications. Excellent implementations will definitely get our attention, and we might even put it in a future hall of fame!

Don’t hesitate to contact us on Discord (#development channel) or Telegram to ask questions about the SDK, give feedback, and propose improvements. If you see something you’d like to improve, feel free to get your hands dirty and create a PR with your changes!

About AllianceBlock

AllianceBlock is bridging the gap between decentralized and traditional finance by remedying issues in both spheres and linking them more closely. They see the future of finance as an integrated system in which the best of both worlds can work together to increase capital flows and technological innovation.

They are building this future by bridging traditional finance with compliant, data-driven access to new decentralized markets, DeFi projects and ecosystem-scaling tools such as funding and interoperability. As such, they are building a next-generation financial infrastructure that aims to provide regulated financial entities worldwide with the tools they need to access the DeFi space seamlessly.

You can also find us on:

Telegram · Twitter · Instagram · Discord · Website · LinkedIn · YouTube · Reddit